Documentation and agile IT projects: never the twain shall meet?
What is the place of technical documentation in agile projects?
During one of the projects I was running, a colleague came up to me and said that we could not call what we were doing ‘agile’ bearing in mind the technical documentation that the client had requested of us as we were designing this computer application for them.
It must be said that compiling documentation is not usually the favourite task of developers, who may be tempted to try and find a way of dispensing with the task altogether.
I did not see things the same way.
As often happens when a new approach is launched, everyone has their own interpretation, and the meaning of each keyword changes in accordance with people’s experiences. If we’re not careful, we can encounter some serious obstacles when communicating with each other.
There’s a simply way you can test for this – with the people around you. Ask a handful of people what they think when they hear a given word. That word can be mountain, crockery, holiday, quality. The word itself doesn’t matter. But you’ll soon see that everyone thinks differently.
To avoid misunderstandings over working methods, I tend to use a main source that is our ‘reference’, which if required I then tailor to specific project needs. The most important task is retooling the words, in conjunction with all the project stakeholders, to fit the present context.
So following my colleague’s outburst, I scurried back to my two main sources to clarify what is meant by agile working. These were:
1. The Agile Manifesto
2. The Scrum Guide
Under the Agile Manifesto, "working software" is deemed more important than "comprehensive documentation".[1]
In the Scrum Guide no precise mention is made of documentation. But it does state that the development team exists to "develop a potentially releasable product increment by the end of each sprint".[2]
Here is how I interpret the two sources:
If the product owner[3] needs to publish the result of the team’s work, this person then requires documentation, so that’s what we must produce. In this case, producing the technical documentation is a requirement stemming from the company’s quality assurance department.
This documentation need not be comprehensive but it must meet the publication purposes of the developed software.
This means that, unlike the old-style development process, in which the specifications are drafted in their entirety before the code-writing begins, the documentation is produced in tandem with the software.
This avoids documenting an item that may not be delivered in the end. And it ensures that the documentation is a one-to-one match with the finished product. Another advantage: some of the documentation can be produced directly on the basis of the code, thus avoiding duplicated information and possible inconsistencies. This is now possible given the development tools available on the market.
Summing up, agile working provides for agility in drafting documentation. It does not mean no documentation at all.
What about you? Do you have similar or different experiences? Don’t hesitate to leave a comment. I'll be happy to discuss it with you!
Artwork: Mélanie Bénard Tremblay, 2020, © Marakoudja.
[1] https://agilemanifesto.org/iso/en/manifesto.html [2] The 2020 Scrum GuideTM, https://www.scrum.org/ [3] « The Product Owner is accountable for maximizing the value of the product resulting from the work of the Scrum Team. », The 2020 Scrum GuideTM, https://www.scrum.org/