Options for Better Documentation

In my last post we explored a number of common approaches to documentation and the ways that they fall short. Fortunately, the story doesn’t stop there - we can (and should) do much better.

What do we need?

To begin, let’s distil some requirements for any eventual solution, based on what we know so far. These are listed in no particular order.

Non-linear access - Our consumers need to be able to go straight to the information they need. We’re not interested in telling stories with a beginning, a middle and an end.

Fast access - Any solution needs to allow someone to get in, get the information they need and then move on. A slow system that makes users wait, or one that requires a lot of process will discourage people from using it.

Convenient updates - making changes to our documentation needs to be as convenient as possible. If someone has an impulse to document something, we want that impulse to succeed; having it stifled by tooling or process is not desirable.

Permanence - we don’t want to write single use documentation. Every time we throw away information by using a transient medium, we are wasting our time. We want to keep documentation around, keep it up to date and have it improve over time.

Discoverability - having documentation that can’t be found is worse than useless. It needs to be easy for users to find what they need, even (or especially) if they don’t already know the exact detail of what they need.

Option: We should use a Wiki

Bringing this subject up in conversation with developer friends, one recurring idea was to use some kind of a wiki - people suggested Confluence, Sharepoint and Roadkill Wiki.

To quote the Wikipedia page definition :

A wiki is a website which allows collaborative modification of its content and structure directly from the web browser. In a typical wiki, text is written using a simplified markup language (known as “wiki markup”)…

In a lot of ways, a wiki can be a pretty good solution - a good implementation can meet all of the requirements listed above.

Considerations

• Plan your structure - for your readers to be able to find the information they need rapidly, the structure of the wiki needs to reflect their approach to finding information. For example, those involved with production support will want to look up error messages or symptoms and find potential remedies to evaluate.

• Embrace the structure of a wiki - much of the value of a wiki comes from the dense interconnectedness of the pages, allowing readers to move from topic to related topic easily. Creating a collection of pages without a dense web of links will cripple the discoverability of information. Some Wiki implementations impose a linear structure to the pages, giving them a fixed relationship - this can be useful, but does not reduce the need for links between pages.

• Use WikiWords - if your tool supports it, use WikiNames (aka WikiCase) to make automatic bidirectional links between pages.

• Use single sign-on - if possible, configure your Wiki to integrate with your existing credential system (e.g. Active Directory) so that users don’t have to remember a separate username and password. If authentication can be automatic and transparent (so that users aren’t prompted for credentials), all the better.

• Performance is critical - a wiki that is sluggish and slow is one that won’t be used. If you choose one of the more heavyweight tools (such as SharePoint or Confluence), make sure your environment is fully resourced and that performance is not artificially constrained.

• Process is the enemy - some products support the introduction of heavyweight process, putting wiki pages through a lifecycle where modifications need to be reviewed and signed off before being accepted. While this might be appropriate for some limit situations (such as your company website), for internal documentation this simply ensures that you’ll have stale documentation that is seldom (if ever) updated.

Option: Publish a static website

Indulging in a bit of “out of the box” thinking, what about publishing a static web site?

Keep the source for a static web site in your source code, alongside your actual source code and use your continuous integration server to compile and publish a static website at a known URL. Possible tools include mkdocs, Jekyll and Pretzel.

Considerations

• Familiarity of tools - By having the documentation live in the same source code repository as the rest of the system, updates can happen using the same toolset that your developers are
  already using day to day. This lowers the barrier for change to almost nothing.

• Focus on content, not style - relying on a form of markup (Markdown is very common) forces authors to focus on the content instead of fiddling around with styling.

• Static sites are fast - The final result is blindingly fast because a static site is as simple as it gets and it can be served quickly and reliably even in a resource constrained environment.

• Minimize the delay - unlike a wiki, there’s a delay between changes being made and those changes being visible to readers; with a good continuous integration environment and some automated deployment, this delay may only be a few minutes.

• Have an About page - one of the pages in your documentation should describe the approach taken for documentation and list both the source code repository and the path required for making changes.

Option: Use Documentation Comments

A standard feature of most modern programming languages is support for some kind of documentation comment - a way to include API level documentation in the source code itself. Making effective use of this is an easy way to improve the documentation of a project, especially because keeping the comments up to date takes only a few moments as you work on the associated code. Possible tools include Sandcastle, Doxygen and SharpDox.

Considerations

• Be informative - your documentation comments need to include information over and above the details that are obvious from an inspection of the code.

• Publish them - use your continuous integration environment to publish your documentation comments to a known URL so that they are easy to reference.

• Stable URLs - some third party generators use a GUID or some other generated ID in their URLs; this is a problem because it means you cannot use deep links elsewhere to reference a specific topic.

• Use External Links - where appropriate, include links from your API documentation to other pieces of information so that readers of the API can easily find our more.

Conclusions

Good project documentation is important - and conventional tools haven’t served us well. Wikis, Static Websites and Documentation Comments are three ways that we can do better.

If you see room for your project documentation to improve (and seriously, whose documentation doesn’t need improvement!) then give one or more of these a try and see how you get on.