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.

NVIDIA announces enterprise servers optimised for data science
“The rapid adoption of T4 on the world’s most popular business servers signals the start of a new era in enterprise computing."
SUSE completes move to independence
“Current IT trends make it clear that open source has become more important in the enterprise than ever before."
Unencrypted Gearbest database leaves over 1.5mil shoppers’ records exposed
Depending on the countries and information requirements, the data could give hackers access to online government portals, banking apps, and health insurance records.
VoiP new-comer upgraded and ready to take on NZ
UFONE is an Auckland-based VoIP provider that has just completed a massive upgrade of its back-end and is ready to take on the market.
Online attackers abusing Kiwis' generosity in wake of Chch tragedy
It doesn’t take some people long to abuse people’s kindness and generosity in a time of mourning.
SAS announces US$1 billion investment in AI
"At SAS, we remain dedicated to our customers and their success, and this investment is another example of that commitment."
IntegrationWorks continues expansion with new Brisbane office
The company’s new office space at the Riverside Centre overlooks the Brisbane River and Storey Bridge.
DXC subsidiary takes SAP energy industry partner award
Winners of the awards were selected from SAP’s A/NZpartner ecosystem and announced at the recent SAP A/NZ Partner Kick-Off Meeting held in Sydney.