How much documentation is enough?

• According to the Agile Manifesto agile practices focus on “working software over comprehensive documentation“. Many people have interpreted this as no documentation, but nothing could be futher than the truth. Documentation is an essential part of any project, whether it is done in agile or waterfall, the question I am often asked, however, is how much do you need to produce?

As a consultant in Canberra I’m often working with government clients who are all used to Waterfall project management. Their process typically goes something like:

1. Create a high-level requirements document — including project background, context diagram and basic use cases
2. Determine the costs of the project based on the high-level requirements document — speculate the cost is about +/- 30%. I’ve heard that some people just count the number of use cases as their basis for how much the system will cost
3. Create a medium-level requirements document — including functional (system behaviour) and non-functional requirements (system constraints)
4. Refine the costs of the project based on the greater level of detail in the new requirements document – speculate the cost is about +/- 20%
5. Create a detailed-level requirements document — including detailed use cases, alernate flows, screen concepts and logical data model
6. Refine the costs of the project based on the very fine level of detail in the new requirements document – speculate the cost is about +/- 10%

I’ve seen this process take anywhere between 3 and 6 months to complete. Each document is considered and then signed-off by the business as representative of their needs. A meeting is then conveined with the project stakeholders, including project manager, developers and business analysts, where the budget is assessed and agreed to. Once complete, then the BA can engage the development team to begin discussion on how the system will be built. Some six months after the first stage of analysis, the build then begins.

It’s been suggested to me that all of this documentation is required “because we’re government”. When probing a little more I’ve generally found the following reasons are given:

1. The business needs comprehensive information to sign-off and approve the build
2. Developers need to know what the system is designed to do
3. Other developers need to know how the system was built in order to do improvements
4. Other developers  need to know how the system was built in order to do maintenance
5. The government requires sufficient information in order to know why money was spent and how it was spent

In my experience, however, very few people in the business understand requirements documentation. They tend to read through the project background to make sure the current state and rationale for the project is clearly articulated, they might go through the business process maps because as a graphical depiction of the project it’s easier to understand than a use case. But overall, getting them to sign-off and approve something they’ve not seen is a bit … well … it’s just not logical.

What about making improvements? IMHO very few systems are ever revisited. When budget allocations are made it’s usually a once off in order to support a program of work. Once the program is finished there is no more money. The later, though, is a fair point. The question is, therefore, how much actually needs to be formalised as a document?

Articulating the context

• Personas: Describe on a single A4 page each of the human actors in the process and what they need to get out of the system being built. These translate to story cards in agile where you can specify “as a <user> I need to <activity> in order to <outcome>”
• Scenarios: Describe how the persona will interact with the system. Story boards are a useful graphical tool that ensure the context, flow, and interaction points with the system is logical before building begins. Scanerio-based requirements are becoming more the norm within the business analysis and even engineering domains. I’ve usually workshops the scenarios in sprint planning and obtain sign-off regarding the priority of the ranking. Don’t forget to make note of some of the system metrics and contraints within the scenarios, including things like volumetrics, system uptime, system support, security, and business continuity planning
• Context diagram: Showing the connections and interactions between the human and technical components of the system

Describing requirements

• Process maps: Note the alignment between the scenario, the business process and the supporting systems components/interactions/behaviour that are required. Using business process modelling notation (BPMN) is one effective tool to use. There are a number of ways to do these diagrams, but my favourite method tends to be one that makes good use of swimlanes and notes the human-system interaction as well as the supporting business processes/rules.
• Requirements/treaceability matrix: Ensure that each and every requirement can be traced back to supporting the user as described in his persona description. Ensure that each requirement notes the scenario it came from. In essence, this combined with the process maps, can replace use cases (in fact, I almost never use them now). Using a mind mapping tool can be a useful way of showing the relationships between these elements. Good tools like Mind Manager can even aggregate smaller mind maps into a single large one, but when things get really complex nothing beats good old Microsoft Excel.

Documenting the solution

• Logical data model: Show how the requirements and context diagram converge as a data solution to support the users’ processes. This should only be a single A3 page.
• Site map: Show how do all the steps in the scenario and supporting processes relate to ‘pages’ required in the system. An Information Architect (one who makes information usable by people, as opposed to a Database Architecture who makes information usable by machines) is a good person to have in the project to take on this task.
• Navigation design: Indicate how the navigation will work, including the primary, secondary and tertiary elements, to help users navigate between the pages in the site map. Draw from pattern libraries like one managed by Yahoo! to ensure you’re basing your solution on accepted standards and practices.
• UI design: Document how the data model, site map and navigation design all come together on the screen.

Validation of the solution

• Prototypes: Show how the solution will work with the scenario documented at the beginning. If the navigation design is clunky, or if the flow just doesn’t seem right, then there is something wrong with how the elements of the solution come together — for example, giving too much emphasis to putting the data on the screen, rather than to ensuring its display and navigation makes sense to people using it. Many of the elements of traditional UAT can be done here by demonstrating to the business and system users that the system is going to work in the way they need it to work. Gaining sign-off at this point is much more logical because business owners can actually see what they’re now going to get. If you’re working with a Waterfall process, then this is the point at which understanding the costs of the build is much more efficient. In essence, the prototype reflects the intent of what you’re going to build.

If the client loves to read documents and insists on examining each one and signing it off then I typically:

• Print out the whole thing
• Put it into a ring binder
• Create a preface that details the project’s goals, aims, etc.
• Create a table of contents that describes each of the light-weight deliverables
• Put a single sign-off sheet at the front for the person to physically make his signature (because if they’ve asked for documents then this is often what they mean by sign-off) 

In agile environments I tend to obtain sign-off at the end of each two-week sprint by demonstrating that the scenarios the business and system users have indicated are important to them have been articulated as a prototype. It’s important they understand at this point that their sign-off represents the following:

• The prototype supports the scenarios they signed-off on at the beginning of the sprint
• The prototype represents the way users want to work 
• The prototype represents a better, smarter way of working — answering the ‘how well‘ question

All the rest of the documentation created is really only for you as a way to get to a solution. As documentation for the official record as to how you came to that solution, they describe the steps quite well, and even adhere to the ISO13407 standard. The prototype, supporting screen types (wireframes), and data models represent the best means of communicating to developers what to build. If you’re working in an agile team it’s likely that the developer has created the prototype as a way of demonstrating he understands what is required of him in a real build.

Documenting the system build

Of course, the way the system is actually built is another thing entirely. Creating a large document that is then signed-off by the business before the system is built only speculates what has not yet come. Documenting the system after it is built makes much more sense, particularly given the surprises that may come in transfering the intent (as shown in the prototype) into reality.

So what needs to be documented at this stage of the process?

• Code: Make good use of notes within the code so that when/if it fails in production a developer can understand what was developed and how by looking at the source and comparing it to the testing regime
• Testing regime: Articulate what you tested, how and what were the results. Making use of automated testing  tools typically makes this task a whole lot easier
• Physical data model: Show what the data model looks like now that the system is finished, rather than requiring it to be built in the way you speculated earlier

Advertisement