Want A Thriving Business? Focus On Smart Documentation In Agile!

Want A Thriving Business? Focus On Smart Documentation In Agile!

Detailed documentation has been an integral part of the process in traditional approaches to software development, often considered a strategy to reduce risks. However, trends of development are changing, so do the document approach need to evolve without costing the evidence of the testimonials.


As Agile practitioners, one should strive for efficient documentation rather than too much documentation.

In non-agile models like the waterfall, the requirement of documentation happens early and the rest of the supporting documentation comes later in the game before release. If QA encounters issues which may need code revisions, documentation may have to undergo quick revisions too. This can possibly result in incomplete, inaccurate or poor documentation, as no one actually verifying the documentation updates, unlike the code revisions. The solution to this problem lies ONLY in following efficient documentation along the way, the strategy followed in Agile methodology. Practitioners interpret Agile as “Working software over comprehensive documentation”, wherein, core pieces including requirements/stories are documented and maintained from the start. Creation of any supporting documentation can also be created like a task/story with a clear owner ensuring maintenance along the way.

But how much is enough documentation in the fast-paced development world we all operate in?

A documentation task should always look at the purpose, usage, maintenance effort, and long term value. Here are some potential reasons documentation comes in handy in Agile:

  • To create a common understanding – Most often we assume everyone in the team is on the same page but when things are put on paper i.e. when things are designed, it is then that a few understand that the actual understanding is different from what they had actually perceived. It is always helpful to divide teams into smaller groups and let them brainstorm through different requirements. They can then come up with workflows or data flow diagrams which can then be used to explain understanding with other teams and fix gaps if any. Ideally, this is done before the Sprint planning meeting or even during the meeting to ensure the exercise becomes productive at the very start.
  • Surface and understand complexity – Sometimes it is not easy to understand certain flows of the application  such as the relation between different fields or how the data is fetched from the back-end. While analyzing complex problems, we need to document them for common and clear understanding.
  • Create empathy – Documentation is not just about black and white requirements. A lot of focus is late coming in on user pieces, especially understand their requirements and building empathy, along with emotional quotient in what is delivered. Not all may interpret this on the same page. At least early on in the process until a user mindset is inculcated, documenting some of these will help the team mature in its understanding.
  • Knowledge Transfer and Ramp up – this continues to be a strong reason for documenting core pieces as new members are inducted in the team. Herein focus should be on giving a base knowledge from whereon the actual product should speak for itself.

Documentation will remain one of the main aspects of any development lifecycle and Agile is no exception.  It needs to be handled responsibly to ensure value and this buy-in has to come in the top down in the .

About the Author