We tried following a client's getting started guide
Half the code examples didn't compile.
Last week a client asked us to review their getting started module. The manual installation section was deeply technical: lots of steps, lots of code blocks, lots of commands to run in sequence.
We started following it. Within a few minutes, we had our answer. Some steps worked fine. Others didn’t compile. One snippet referenced a method that no longer existed. Another used a dependency version from two releases ago.
The client didn’t know. The page looked great. Clean formatting, syntax highlighting, clear explanations between each code block. Nothing about it screamed “broken.” You had to actually run the code to find out.
This is what happens when code lives in Markdown files, disconnected from any build process. Nobody re-runs examples after every release. The docs look fine. They just don’t work anymore.
Keep examples in a project, not in your docs
The fix: stop pasting code into Markdown files. Instead, keep your examples in a separate project that actually compiles.
The project lives in its own folder near the docs, with real dependencies, a real build step, and version control. Your docs import snippets from this project instead of containing them directly. When the product releases a new version, you update the project. If a snippet breaks, the build fails. You find out before your users do.
You can also version your examples properly. Need docs for v2 and v3? The project has branches for each. You bump the dependency, run the build, and know immediately what still works.
Once we set this up for the client, updating code examples stopped being scary. It went from editing a Markdown file and hoping it still worked to making a code change with a build. New users following the getting started guide actually got to the end.
It does mean maintaining a project alongside your docs. But the alternative is finding out your examples are broken when a user does.
If you want the practical details on how to set this up, I wrote a step-by-step guide a few years ago.