One of the 4 values of the agile manifesto is ‘Working software over comprehensive documentation’. Does this mean we have to write no documentation at all? Most definitively not! It means that working software has higher value than documentation.
If we embrace that value, what level of documentation should we maintain?
When searching the net on this topic, I found an interesting essay on the website of Scott Ambler. It is called ‘The TAGRI (They Aren’t Gonna Read It) Principle of Software Development’.
He makes the comparison with YAGNI, which says not to add functionality that might be needed in the future. Stick with what is needed to get the current feature running, because the future functionality may never be implemented due to re-prioritization or changing business demands.
The TAGRI principle says: ‘Only model/document with a purpose and create agile documentation which reflects the true needs of the audience for that documentation’.
Please read the article to get the detailed explanation about TAGRI.
At my current project, due to the large set of complex business rules and the expansion of our team, we needed to create more detailed documentation.
This is why we created a central definition repository, which is a structure that more or less reflects the domain model. Every domain object has a small document describing its properties, relations and behaviors. All reference data that is used in several domain objects, is extracted and centralize in a reference document. This makes sure that an update to a single piece of information is only needed in one place. We refactored to this structure a month ago and will see how this works.