A client asked us to review their getting started guide. The manual installation path had a long sequence of commands and code examples, so we followed it from the beginning and ran everything.
Some examples worked. Others did not compile. One called a method that no longer existed. Another used a dependency version from two releases earlier.
You could not tell from the page. The formatting was clean, the syntax highlighting worked, and each code block had an explanation. The failures appeared only when we ran the code.
This is what happens when code lives in Markdown files, disconnected from any build process. The docs look fine, but 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.