Random Acts of Architecture

Wisdom for the IT professional, focusing on chaos that is IT systems and architecture.

In Defense of Documentation

Anyone who has spent a modicum of time working with software developers learns that developers hate creating designs, use cases, “readmes”, code samples and similar technical documentation. Agile proponents point to the “working software over comprehensive documentation” principle and Lean proponents claim documentation is “waste” since it does not directly contribute to the finished product or customer value.

They have a point. Writing clear, understandable documents is hard and it takes time away from coding. Keeping them up-to-date when inevitable changes occur is similarly time-consuming, particularly large changes or redesigns. Consequently, many stop asking for documentation, exacerbating poor or absent documentation. Many developers argue “code is documentation”. It is always up to date and developers had to work to understand it. Why shouldn’t everyone else?

However, saying “code is the only documentation” is a fallacy. Well written and designed code and indicative automated tests can be good documentation but every project includes code the developers are not proud of. Software developers often think of themselves coding like athletes lining up for a race at the Olympics. They have spent years training and are lining up to compete under perfect conditions. However, frequently code is written when developers are tired, stressed or unfamiliar with the problem or tools and this produces less correct and readable code.

Also, and arguably more important, developers are not the only audience for technical documentation. QA (testers), localization, management and documentation writers (those that write the manuals and non-technical documentation) all need technical information about the product and usually cannot read code, at least not well enough to get the information they need time efficiently. Developers new to the product also need a starting point.

Part of the problem is that documentation, particularly in larger organizations, consists of word processed documents or E-mail. E-mail in particular is a poor choice since it is only available to the recipients and often gets lost. An internal Wiki is a better choice, since most maintain a change history, have centralized storage making the latest version easier to find, support access control, provide auditing and can notify users of changes. Wikis are not perfect, however, since their storage formats are often proprietary and they often lack features of modern word pressing tools.

Wikis also encourage splitting documentation from large, monolithic documents into smaller sections. Care must be taken to ensure consistency and information is easy to find but most Wikis support free text searches. This fits better into the Agile and Lean methodologies, where smaller documents are delivered when needed rather than complete documentation delivered up front.

Writing documentation forces developers to identify and empathize with their customers or other developers, encouraging them to simplify the product’s design, user interface, installation and/or configuration. Some techniques, such as Documentation Drive Development and Readme Driven Development, encourage starting from the documentation for this reason.

It seems that literacy has become a skill in the software development industry. We have fooled ourselves into thinking that developers are only productive if they are writing code and poor documentation is acceptable. As Albert Einstein said “If you can’t explain it simply, you don’t understand it well enough.” Writing documentation forces developers out of their warm, cosy technical silos and back into the user world, reaquainting themselves with the problems the software is trying to solve.

3 responses to “In Defense of Documentation

  1. Colin Taylor (@coltnz) August 27, 2012 at 12:41 pm

    One trick we’ve started to use is to generate our API docs, REST mounts and code interfaces off the same YAML files. As you suggest this forces developers to think of their customers (very early on in the process) and has the added advantage of bringing the documentation into the build process where it can fail fast too.


    resource: PolicySet
    summary: Policy Sets are used to group..
    – update:
    description: “Update details of ..
    method: PUT


  2. Vishal Asthana September 7, 2012 at 4:49 pm

    Makes sense. Do share ways you’ve found effective in improving an internal Wiki.

    • Anthony Langsworth September 7, 2012 at 6:21 pm

      First, it is important to choose a good Wiki. Choose one that (1) Is well maintained and has good support, (2) Supports user authentication and has access control on documents or namespaces, (3) Tracks changes to documents and provides a history, (4) Allows E-mail notification of document changes and (5) Has a good editor, preferably WYSIWYG, and supports lists, tables and uploading images.

      The biggest thing an development team Wiki needs is a “gardener”: someone who is responsible for determining the layout and structure of documents in the Wiki. It does not have to be a full time role but the gardener should have strong English and an aptitude for explaining things well. The gardener should create standard templates for pages, naming conventions and determine what namespaces are required.

      The gardener is not responsible for creating the content, more enforcing its structure. For example, if someone makes a change to a product, the gardener is not responsible for making the change to the Wiki. However, the gardener is responsible for making sure the change gets made and that it is done according to the guidelines (not just tacked on to a separate, unlinked page, for example). The gardener may review the changes or delegate that to someone else.

      It is important to structure the Wiki to meet the needs of the audience rather than the needs of those creating content. For example, if you have a dedicated UI or security or localization team for software development, do not put their information in separate sections. Put them in the same section that the developers are looking at. Having everything together makes it much easier to find, ensures things do not get missed and identifies out of date content faster.

      A Wiki needs a change in mindset. Many companies are used to information being forced upon them. A Wiki allows the consumers of the information to modify it. This should be strongly encouraged (and rewarded if need be). If inaccuracy is a concern, have reviewers configure the Wiki to E-mail them when modifications are made.

      An development Wiki needs a strategy to handle versioning. If you have a set of documents for version 1.0, what happens when version 2.0 is released? Some of the documents for version 1.0 may still apply to 2.0 but some may be superseded. What if a change is made to a 1.0 document after the release of 2.0?

      A Wiki needs some way of measuring success. How many people are using it? Did they find what they were looking for? You do not necessarily need a large, unsightly rating and comment box at the bottom of the page but a simple “E-mail a Human about this page” link may be helpful.

      Lastly, the usage patterns of a Wiki will change over time. Remember to review any standards periodically to ensure they are still meeting the Wiki’s needs.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: