IT Brief New Zealand - Technology news for CIOs & IT decision-makers
Story image
Thu, 6th Nov 2014
FYI, this story is more than a year old

Quality and context, rather than quantity, define just enough documentation.

How many times have you seen a requirement document which goes over hundreds of pages with structure so complex that it is difficult to find the embedded requirements to get them signed off?

One of the biggest challenges for any BA in the modern, fast paced project environment is to balance the required level of documentation while keeping them light and up to date. For some ‘just enough’ is a concept important in an agile environment only; for me it is important in any project environment, agile or traditional.

Every project environment has one thing in common: they all have some sort of documentation. No project can be successfully run with just verbal conversations.

The key ingredient for just enough documentation is to understand what the next goals are. It encourages lightweight easy-to-understand and maintain documentation. But then how much documentation is ‘just enough’?

There is no hard and fast rule on this and each project needs to define their own rule to fit the environment and vendors they are working with.

For a start, it should be a document which has enough details for the stakeholder to express their needs, and enough details for the designer/developer to deliver a solution to meet the stakeholders need.

Produce the least amount of documentation needed to facilitate the most understanding. It makes business sense to write less documentation and focus more on early delivery.

Shared understandingIn my many years of experience I have rarely come across a project which lacks documentation, but many times I have come across documents which are of bad quality or obsolete and prepared with good intention but rarely used.

I have been in numerous meetings where the author explains the document, clearly proving that conversations are more important than documentation to ensure common understanding. Always remember ‘shared document’ does not mean ‘shared understanding’

Traditional requirements documents have the following characteristics• Detailed• Heavy• Complete• Sign off• Estimated• Prioritised

On the contrary, just enough documents have the following characteristics• Just in time• Light• Prioritised top down• Estimated in relative size rather than effort• Gathered collaboratively• Focus on breadth rather than depth• Assumes changes

Just enough documents for the first round of release may contain

• High level business process• High level architecture diagram• High level information/data diagram• Wireframes (for look and feel)

When writing any documentation, you don't simply need to think about what is still missing, but also what you have that you don't really need. Personally I prefer to have lots of diagrams, where appropriate, instead of lengthy text.

On the final note ‘just enough’ does not equal ‘not good enough’. It's not a matter of quantity, but of quality and context.

Jayesh Jain works in information technology and services and was recently appointed as vice president, membership, for IIBA’s (International Institute of Business Analysts) New Zealand chapter.