Story image

Just enough documentation

06 Nov 14

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 understanding
In 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.

Disruption in the supply chain: Why IT resilience is a collective responsibility
"A truly resilient organisation will invest in building strong relationships while the sun shines so they can draw on goodwill when it rains."
The disaster recovery-as-a-service market is on the rise
As time progresses and advanced technologies are implemented, the demand for disaster recovery-as-a-service is also expected to increase.
Apax Partners wins bidding war for Trade Me buyout
“We’re confident Trade Me would have a successful standalone future," says Trade Me chairman David Kirk
The key to financial institutions’ path to digital dominance
By 2020, about 1.7 megabytes a second of new information will be created for every human being on the planet.
Proofpoint launches feature to identify most targeted users
“One of the largest security industry misconceptions is that most cyberattacks target top executives and management.”
What disaster recovery will look like in 2019
“With nearly half of all businesses experiencing an unrecoverable data event in the last three years, current backup solutions are no longer fit for purpose."
NVIDIA sets records with their enterprise AI
The new MLPerf benchmark suite measures a wide range of deep learning workloads, aiming to serve as the industry’s first objective AI benchmark suite.
McAfee named Leader in Magic Quadrant an eighth time
The company has been once again named as a Leader in the Gartner Magic Quadrant for Security Information and Event Management.