Story image

Just enough documentation

06 Nov 2014

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.

General staff don’t get tech jargon - expert says time to ditch it
There's a serious gap between IT pros and general staff, and this expert says it's on the people in IT to bridge it.
Flying high: How airline Scoot enhances the customer experience
Singapore Airlines’ low-cost arm Scoot has selected Dell Boomi’s platform help it better understand its customers – and its own business.
Chorus partners with Nlyte, expands edge data centre offerings
Chorus announced today that it is going ahead with expanding its Chorus EdgeCentre Colocation product to three sites across New Zealand.
Schneider shares advice for solving edge computing challenges
Schneider Electric has shared the findings of a new whitepaper that delves into the issues of deploying IT at the edge.
DimData: Fear finally setting in amongst vulnerable orgs
New data ranking the ‘cybermaturity’ of organisations reveals the most commonly targeted sectors are also the most prepared to deal with the ever-evolving threat landscape.
Y Soft and Brother partner to enhance print management
YSoft SafeQ integrated print management and document capture solution is now embedded in Brother multifunction devices.
F5 acquisition of NGINX now complete
The companies have released blogs on the topic, explaining how NGINX will now operate as a unit of F5, and the benefits they expect this merger to bring.
IXUP goes "post-quantum" with security tech upgrade
The secure analytics company has also partnered with Deloitte as a reseller, and launched a SaaS offering on Microsoft Azure.