DEV Community

Burdette Lamar
Burdette Lamar

Posted on

9 2

Keep Your Example Code Green

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.

Postmark Image

Speedy emails, satisfied customers

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up

Top comments (0)

Bump.sh

Hate writing docs?

Hate undocumented APIs even more?

Bump.sh generates an always up-to-date API reference site for REST and Event-Driven Architectures.

Plug it in your CI. It fetches your OpenAPI and AsyncAPI (GraphQL pending) spec files, and even generates a diff. Gather all of your API docs in a single source of truth.

Try it for free

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay