Effective Documentation

by Krishna on February 23, 2007

When it comes to documentation, software development teams follow two different schools of thought. I am oversimplifying below, but bear with me:

  1. Documentation is good: For every process, there is a document to plan it, define it, record it and audit it. Every line of code generated will have several lines of corresponding documentation. Likewise, there are more managers, analysts, designers and technical writers than programmers.
  2. Documentation is bad: Why waste time writing documents when the coding is so easy? Besides, good programs should be self-documenting. The market doesn’t reward technical documents — it only pays to deliver faster.

Like every black-and-white scenario, each side has good arguments. Before we start on that, let us establish some premises:

  1. Every software application exists to provide a solution to a problem. It will have one or more end users who need it.
  2. The sooner the application development is complete, the more likely the product will be used. Otherwise, there will be substitutes in the form of competing software products, manual processes to resolve the problem, etc. Hence, a necessary aim of the product development should be to deliver it as quickly as possible with the necessary functionality.
  3. Unless the software application is reasonably stable and consistent, it cannot be termed as providing a solution. Hence, the other necessary goal of product development should be good quality.
  4. It is possible to achieve a high score in one goal (delivery speed, software quality) at the expense of the other, but that only defeats the primary purpose of end users using the application.
  5. Hence software development of any application should strive to find a medium — necessary quality delivered within a reasonable timeframe.

Software documentation should be subject to meet that fine balance. Hence the two questions are

  • How little documentation do you need to maintain without sacrificing the necessary quality?
  • How much documentation can you do without exceeding a reasonable timeframe?

Asking the opposite question in each case will lead to what we discussed at the beginning of this article. For example, you can maintain high levels of quality by having all sorts of documents. And you can also shorten delivery timelines by deciding to do very little documentation. To achieve both, you need to strike a balance and find how to do effective documentation.

A simple set of rules I recommend to people is:

  • Easy to write, easy to understand and easy to maintain: Reduce redundancy — this will reduce the need to update multiple places in the document. Follow common documentation conventions (industry, company or project-level documentation standards). Write in simple English. Find out from your team if they understand what you are writing.
  • High level of accuracy and completeness: Make sure what you write is correct and comprehensive as far as you know. Verify the documentation with end users, if possible. Get frequent feedback from your team. A common issue I find in requirements documentation is “logic fatigue” — sometimes the person just writes a heavily-loaded sentence with no explanation because they are too tired to explore all ramifications of a particular functionality.
  • Fewer documents with greater depth: Maintain a small set of documents with more detail instead of producing more shallow documents. This makes it more efficient and easier to manage when change requests come in.
  • Control change management: Although it is hard to prepare good documentation in the first place, it is even harder to maintain them when the inevitable changes come. Use tracking features in your task management and bug tracking tool to ensure that all changes are reflected in the documentation.

Many aspects of documentation, especially audit-related documents, can be reduced, at least in frequency, by proper resource allocation and training. Development staff members, who are very knowledgeable in standards and best practices, need less process and, by extension, less documentation.

Now an observation to round off this article: Although more documentation is directly related to good quality and inversely related to delivery times, nearing the boundary conditions of 100% or 0% documentation may sometimes result in both poor quality and poor delivery schedules.

When the team tries to have 100% documentation (without any streamlining of the process), change management can be overwhelming. Minor changes in the application can result in disproportionately large changes in the documentation. At this point, the team is under greater pressure from the end user to close bugs and release the software.

Without high discipline, there may be inconsistencies in making changes in all parts of the documentation, which again results in wrong specifications or design - further leading to confusion. A cumbersome process easily lends itself to being violated easily. And suddenly the whole pack of cards comes falling down, because no one knows which document is the right one.

The 0% documentation is also severely affected by change management. Although the software development team initially had a quick grasp on the project details, once changes start coming in bits and pieces, miscommunication becomes the norm. Some developers know more than the others and they start stepping on each other’s toes in the code. Functionality starts degrading. The problem is that no documents exists that can serve as the central guide for the team.

So the extremes don’t really work. The best way to run a project is somewhere in between. What that is depends a lot on the capability, maturity and experience of your team. For example, when I use a term “easy to understand”, that can translate into entirely different things for different people. It is up to you to figure out what that means in your context and put the right effective process in place.

Comments on this entry are closed.

Previous post:

Next post: