Skip to Main Content

software documentation in the age of agility

Scribble Image as Placeholder

Many teams struggle with writing documentation. How often should we document? How detailed should the documentation be? How do we keep our documentation up to date? These are important questions and getting it wrong can waste time and drain efficiency. I recently coached a team that spent 10 hours per sprint updating documentation that never got read. In this article, I'll share some helpful DOs and DON'Ts for managing documentation in an agile environment.

DO make sure that documentation is always secondary to the discussion. Teams should meet to achieve a specific goal, not to "review documentation". Documentation can be produced or reviewed as a means of achieving a team's goals, but should always play second fiddle to said goal.

DO remember that clean and organized code is the best form of agile documentation. If the code is properly commented and formatted, developers won't need a document to tell them what the software does.

DO cultivate a "throwaway" culture when talking about documentation. When most documentation is treated as disposable, it means the team isn't wasting valuable time updating documents that won't be read. We should only keep physical objects that spark joy, and we should only maintain documentation that provides direct value.

DO keep reference documents. Not all documents should be thrown away. One example of a good living document is the reference sheet. This kind of document is living because it is constantly referenced by the team. If you can imagine it being printed out and pinned to a cubicle wall (like a list of server names), then there may be value in keeping it updated.

DON'T create zombie documents. Zombie documents are those that are maintained solely because "it's the way we've always done it" or "it's our policy". These documents stick around, not because they generate value for the team, but because legacy procedures call for it.

DON'T maintain documents "just in case". A common type of documentation-induced waste that I encounter comes from the desire to maintain documentation just in case a member of the team "wins the lottery". The thinking is, if this person leaves, their organizational knowledge should be easily transferred to their replacement via a document. In reality, however, these documents prove to be of limited use. Not only are they difficult to keep properly updated (and so will often be out-of-date), but new people learn best by collaborating with the team, not by reading documentation.

DON'T use documentation as a proxy for collaboration. Busy people are always looking for ways to streamline their days. One common way for this to manifest is by asking for documentation as a way to stay informed. IT managers may ask their teams to put together status updates, or downstream teams may ask upstream teams to send documentation with work products. This practice is like burning a candle at both ends. Not only are teams spending time creating low-value documentation, but it also likely means that individuals are not collaborating as closely together as they could be.

DON'T forget that we work in complex systems. Software systems are extraordinarily complex and are nearly impossible for a single person to fully understand from start to finish. Some teams are tempted to try and document every small system detail with the belief that, once the whole system is documented, the ambiguity and complexity will diminish. This is, unfortunately, not the case. Systems evolve faster than their documentation. As such, when a reader consumes detailed system documentation (rather than reading the code itself), they are often getting an inaccurate picture of system behavior. This misalignment creates confusion and confusion creates complexity.

In summary, creating and maintaining documentation is a practice that most of us don't worry much about. But with some intentional thinking, we can improve the efficiency of our teams by removing document-induced waste. Hopefully, this article can act as a starting point as you reflect on your policies and practices around documentation.