Showing example code in your documentation is immensely helpful to your user -- unless the example code is stale or, much worse, broken.

If users runs your example code and it gives errors, how can they have any confidence in the rest of your code.

Question: What to do?

Answer: Run your example code before every commit. (Just like your tests, right?)

Question: How?

Answer: Use a build procedure and file inclusion:

• Store each example code snippet is in a separate file.
• In your main document, specify file inclusions for each example code and its output.
• Have the build procedure (Makefile, Rakefile, Ant, whatever):
  1. Execute each example, capturing its output to a separate file.
  2. Run a file inclusion process that merges each code snippet and its output into the main document (README, whatever).

So far, so good.

But over at GitHub, the markdown processing does not support file inclusion.

Shameless plug: My Ruby gem markdown_helper is a markdown pre-processor that does support file inclusion. In fact, the project's front page itself makes extensive use of the feature.

So if your project is on GitHub, you can use markdown_helper to merge code and output into your markdown pages.

And, by the way:

• Your project need not be coded in Ruby. The markdown_helper has a command-line interface that your non-Ruby build procedure can use.
• File inclusions can be nested: your included files can include still more files.

Check out the use cases.