Document Essentials - a missing (agile) practice

Agile documenting: something is missing

Agile principles and practices such as KISS, YAGNI, TAGRI, Single Source of Information, Agile Documentation, are responses to the waste, ineffectiveness or even lack of feasibility of approaches such as BRUF – Big Up Front Requirements, BRUD – Big Up Front Design, and of so called “comprehensive documentation”.

See also previous post: Practices and principles for an economic documentation. 

There is still a missing part: most of the good advices are about reducing the amount of documentation, but no one tell us what is the minimum that could not be ignored.

What is missing: Document, Protect and Use the Essentials

With both “big”/”comprehensive” and “simple”/ “agile” approaches we could have a very unpleasant surprise: the most important, essential information is not available for the ones that must use it.

When “comprehensive” destroy the essentials

Too many time the “comprehensive” documentation is practically done in these ways:

• Unstructured, hard to read and navigate text – the essentials are hard to find, understand and validate
• Only the volume of the documents it is evaluated, but not the coverage of the essentials parts

Finally, we have a lot of text, that cannot be validated and we cannot guarantee even that the main decision areas are covered. The focus is on quantity and not on quality and value of the information and a lot of effort is consumed for poor results.

When “agility” destroy the essentials

One of the main reasons that allow a much lighter documentation in case of Agile is usage of Executable Specification (aka TDD). If you do not have such things it is better to start to think what documentation it is missing.

The main start questions in case of “agility” are:

• I need to “travel light”. What is the minimum needed documentation ?
• I have the right support to distribute the “System Metaphor” to all team members?

Essentials: System Metaphor

Any team member has the right to have access to the System Metaphor – simple explanation of the system design. Beyond self-explained code, you could need a lightweight document(s) that capture this information.  Examples: architectural views, description of main design mechanisms.

Essentials: Business and System Functionality  

Any good developer (and, in particular, an Agile developer) should be able to understand the target business and the main functions of the system. It is very unlikely (!) that this kind of information could be acquired accurately, and in time, only by working from time to time to some details of the system. A lightweight documentation is necessary (beyond practices such as pair programming and moving people around).

Essentials: Data   

A specific part of the of the business and functionality is the managed data & knowledge: meaning, relationships, usage. Examples of some useful lightweight overview documentation: Glossary of Terms, Domain Model.  

Essentials: Main functional flow   

Examples of some lightweight overview documentation: Epics, High Level Use Cases.

Essentials: YOU ARE GONNA NEED IT!   

Here are some real examples of possible consequences for the cases when team members have no easy access to essential knowledge about the product:

• No other alternative for team members to get in-time this knowledge
• Team members work for years on products without knowing essentials
• Team members implement change request and fixes on components where they do not know the functionality and the design
• Testing is not effective with severe consequences on quality and economic
• The undesired complexity and technical debt increase too much with all consequences (fragility and similar)
• The system fragility increase too much (also rigidity, viscosity, immobility) and customer trust will be lost
•  New team members are hard to integrate
• Product ownership handover is a high risk operation

Principles for “Document Essentials”   

Document essentials! – you have no other alternatives to timely, effectively and efficiently distribute this information to the team members.

Present the essentials! – avoid TAGRI. Face to face conversation is the best way to present the documented essentials. 

Protect the essentials! – this kind of information shall not be sunken in an unstructured high volume information. Keep it clear, clean and updated!

Use the essentials! – already having this information and not using it – that it is the greatest guilt and the greatest waste considering the lost benefits.

 Remember: It is very unlikely to make essentials known without document it & present it.