Documentation That's Always Up-to-date

If something is not worth doing, then either don't do it; or automate it. Depending on your vantage point, automating documentation makes the argument of whether or not something should be documented somewhat moot.

Documenting License Compliance

We built a small utility to scours installed command line applications and extract man-page information to document the description of the tool, and more importantly it's license to ensure that you are properly following our restrictions for incorporating a piece of code.

This was equally applied to installed gems and leveraged the power of bundler to not only document directly referenced third party gems, but also the gems those gems are using (and so on).

The results are publishable to a WIKI for easy reference, and executed each time the projects are updated, but using GIT hooks

Extracting Information From Git Commits

With just a little bit of structure, a lot of information can be extracted from repository commits. We built a tool that reviews git commit messages and re-constructs a change-log history that reflects all task commits (i.e. those with associated bugs). We tied things into GIT and Jira, but with small tweaks any bug management tools, or repository would work.

The above examples are small, simple steps to help automate your documentation needs. Simple works best.

Building DSLs For Execution and Documentation

On a more fundamental level, you can incorporate DSLs into your applications that act as both the platform for code execution, as well as rendered into a human-readable format like HTML, or WIKI. In the umple language, we introduced a EBNF format for parsing Umple languages (a model-oriented language that compiles down to Java, C, PHP, or Ruby). It is also rendered in HTML to accurately document the grammar (same source files, two views that are also in-sync).

A snippet of the Umple Grammar as rendered in HTML is shown below.