One of the values of the Agile Manifesto is “working software over documentation.”
I have seen this value either interpreted such that a software development team does no documentation, or the team struggles with what to document and how much to document.
Well the first interpretation and practice of very little (inadequate) to no documentation is a misunderstanding of the value of “working software over documentation.”
My understanding of core Agile principles is to always focus on delivering value, as quickly as possible. This means to eliminate activities and artifacts that do not provide value. So when it comes to documentation I apply this understanding and only document what is of value. And to document it at the level of detail that will be of value to a reader not only today but in the future.
The next thing a team struggles is how to do documentation during a Sprint?
Let’s consider a software development Scrum Team building a software product. During the Sprint the implementation of a particular Product Backlog Item (PBI) requires a change to the database (it may entail adding a new column to a table, adding a new table, etc.), or to the design of the code.
One approach to ensure that the database design document is updated, is to create a task on the Sprint Board (Backlog): “Update DB Design Doc” or “Update DB Logical Data Model”.
This task can be estimated in hours (of effort) and becomes a reminder for the team to capture the change to the database model and not create “documentation debt”. The Product Backlog Item (aka User Story) is not Done until this documentation task is complete.
This simple approach provides the benefit of:
- Capturing the reasons for design decisions
- Retaining the team’s collective knowledge
- Quicker on-boarding of new team members (who can read the background and context of design decisions)
It is important to remember to capture only the absolutely relevant information and nothing else, that is:
- Why is the change being made
- What is the change
- Technical details about the change
Let’s consider the example of a change to the database model during a Sprint, the documentation should include:
- User is being provided ability to personalize their privacy and security settings
- Three new fields (columns) are being added to the db_UserProfile table
- The 3 new column names and their data types are:
- A – integer
- B – boolean
- C – 100 char text field
The above approach can be applied to other documentation needs that the Scrum Team believes will be of value. This simple approach applied with discipline is very effective and avoids “documentation debt.”
What Do You Think?
Will the above approach work? Do you use a different approach? How effective is your approach?
Share your experience with us at https://www.agilious.com/contact-us/
