Pattern: Value Driven Documentation


All the time.


Documentation is a feature and thus runs the risk of being vestigial. Make sure value drives documentation requirements.


First I would suggest, never add documentation until you know why you need it. Here is why:

  • I've had plenty of experience creating documentation that no one ever looked at.
  • Documentation must be maintained. If the software is updated, the documentation must be too, or it will cease to be useful.
  • If the documentation isn't stellar, people won't use it.
  • Documentation is often lost if it's not embedded into the software.
  • Increasing volume of documentation decreases the utility of the documentation, readers are likely to be overwhelmed and give up.

Consider the value first. In the case of documentation, it's probably best to start with none and later add it after you have assessed the costs of not having it (training/support). If you will have thousands of users, then you may know what the value could be and in this case it would be prudent to discuss documentation upfront. If you start the conversation with "What would the value of documentation be?", instead of "We need X documentation!", you are more likely to minimize the documentation you create and target it to achieve maximal value. Use the value you hope to achieve as a filter to limit the documentation.

Also, make sure you put yourself in the audience's shoes. Ask them for input and make sure you are thinking about their actual needs versus your perception of their needs. As with any communication, you run the risk of failing to communicate!


  • Default to no documentation.
  • Only add documentation after you have identified the desired value.
  • Focus on complexity, don't document simple things.
  • Think of documentation as one of many ways to communicate.
  • Consider the value of a more intuitive interface versus documentation.
  • Consider the value of training versus documentation.
  • Read Martin Fowler's take on documentation of the system internals The Almighty Thud
  • One suggestion, the most successful documentation I've been involved with was very task oriented and geared towards tasks the users were already very familiar with.

comments powered by Disqus

Related Posts