Go on a Documentation Diet

Introduction

Most documents, such as project plans, requirements, and designs, contain long narrative paragraphs that make them time-consuming to write, tedious to read, and hard to find essential information.

Instead, consider banning paragraphs from your technical documents and use tables with single sentences. To illustrate the point, here are some narrative and non-narrative examples.

Project scope section of a project plan

Narrative example:

“It has been said that our killer-app v1.2 is too slow, breaks often (reset is required every 6 hours) and is hard to use, with a learning curve of 1 week. After analysis of several clients the company has decided to upgrade v1.2 and create 1.3. There will be a team located in the US and China to upgrade the system. The scope of the project is to develop a replacement to the Killer-app system that uses v2.9 of the KA database along with new hardware from ABC and the latest OS. This will be accompanied by new training for all support staff and customers that will be web-based. This is a complicated project that will require buy-in from management. The project will run for ten months and be delivered in three phases, the first phase replacing the existing functionality and the remaining phases improving connectivity to other systems.”

Non-narrative example:

Project Scope: Upgrade killer-app 1.2 to 1.3

1	Increase response time from 10 to 1 seconds
2	Reduce reliability from a failure rate of 6 hours to >= 1 month
3	Reduce learning curve from 1 week to N hours (TBD)
4	Use v2.9 of the KA database
5	Use new hardware from ABC + OS (version TBD)
6	Provide web-based training for support staff and customers
7	Improve connectivity to other systems (TBD)
8	Deliver system in three phases over 10 months

Here is another example for a “project constraints” section of a project plan.

Project Constraints of a project plan

Narrative example:

“Constraints are a natural part of any project. Constraints have been well documented over history and can be viewed by Googling “project constraints.” Typical constraints are scope cost and time. This project is no different and has numerous constraints. Firstly, there has been a lot of discussion in the ABC committee on data constraints. It has long been established that we should support CSV and XML files going forward. We also have existing hardware we must support (server A.1, cables B.2, encryption device C.3, and screen resolution D.4).”

Non-narrative example:

Project Constraints

1	Support CSV and XML files
2	Use server A.1
3	Use cables B.2
4	Use encryption device C.3
5	Use screen resolution D.4

 

Replacing long, ambiguous paragraphs with single sentences is particularly useful in requirements definitions since it allows the team to know more clearly what to build and test. It also makes requirements mistakes more obvious.

Product Requirements

Narrative example:

“The system should allow entry of data items relevant for customer payment or allow a user ID to be entered to charge the amount to. If an ID is used, and there are insufficient customer account funds, then either request a credit increase or notify that the account is overdrawn and flag the account as ‘credit-OD.’ Email a receipt of the transaction.”

Non-narrative example:

1.1	User selects a) pay with credit card or b) ID and password
1.2	User enters a) credit card or b) ID and password
1.3	If option “b” selected and insufficient funds in the ID account then offer user a credit increase option
1.4	If credit increase option not selected, then notify that the account is overdrawn
1.5	If the account is overdrawn, then flag the account as ‘credit-OD’
1.6	Email a receipt of the transaction

Another way to describe requirements that have conditions is by use of a decision table. This can also help highlight combinations that have not been accounted for.

	Requirement
Conditions	1	2	3	4
Credit card	T	–	–	–
ID with funds	–	T	–	–
ID without funds	–	–	T	T
Accepts credit increase	–	–	T	F
Outcomes
Payment accepted	Y	Y	Y	Y
Account flagged ‘credit-OD’				Y
Email receipt	Y	Y	Y	Y

Application to other documents

The approach of replacing long narrative text by tables of single sentences or diagrams, can be applied to the majority of technical documents for example:

Project plans

• Scope
• Out of scope
• Customers
• Make/buy/reuse decisions
• Assumptions
• Constraints
• Project lifecycle steps
• Data management plan
• Project stakeholders (roles and responsibilities)
• Required resources
• Training plan for team members
• Measurement objectives

Requirements definitions

• User classes
• Context diagram
• Epics
• User stories
• Use cases
• Non-functional requirements
• Quality attributes

Design information

• Architecture diagram
• Interfaces
• Data formats
• Algorithms

Test plans

• Environments needed
• What to test
• How to test
• Expected results

Summary

If you want to write lots of paragraphs, then become a writer or novelist! If you want to convey technical information quickly and concisely, consider replacing all paragraphs with tables of single-sentence bullets or diagrams.

If you would like help simplifying your organization’s processes or documentation, contact us for a free session to get started.

[Forward this email to your boss! Subject: Here’s a cool tip for you] Quick Link