What level of documentation is required in Agile Projects?

There is a myth in the industry for agile teams, they feel or believe that, if a team is delivering their work using agile methods such as Scrum, there is no need for documentation. This is wrong. I wanted to give more clarity on how to manage the documentation in Agile projects through this article.

First of all, there is one value in the Agile manifesto related to documentation. It is:

Working software OVER comprehensive documentation. 

The above value means, shift your focus to deliver working software instead of starting with upfront documentation. It does not mean that, completely ignore the documentation. In addition to the working software, whatever documentation is valuable, useful, the teams have to create it. 

Also, there is one principle in Agile manifesto, #6 principle:

The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.

The crux of the above principle is, 

• TALK more WRITE less. 
• Shared documentation does not guarantee shared understanding.

Let us understand the different types of documents:

Project documentation: This is the documentation useful for the teams who are working on the project. These documents help the teams to execute the project. Examples of project documentation are: Requirements specification, Design, Architecture documents, Database architecture, and so on. 

Product documentation: These documents are useful for the end users that help them in using the Product. Examples of product documentation are: USer guides, Release notes, Installation notes, Troubleshooting document, FAQs and so on.

Based on the need, the teams may need to produce some project documents and some product documentation also. So, while they create the documentation, they can take two approaches as listed below:

Document late: In this approach, the teams focus on creating the features and get them potentially releasable in every Sprint. Before going for release, the teams can take up the required documentation work. Along with the increment they also provide the documentation to the users.

Document continuously: In this approach, the teams will include the documentation within their Definition of Done and they create required documentation during the Sprints itself. 

Both options have their own pros and cons, so depending on what is convenient for you, you can choose the approach. My preference will be the “Document continuously”. 

Ask yourself below questions before creating any document so that it helps you prevent unwanted documentation:

Is the document for internal purposes such as hand-off to another person within the team?

Can you discuss the information through a face-to-face conversation?

Can you share the content through code instead?

Can you communicate through a drawing, picture, or other lightweight model instead?

If the answer is no to the questions above, what is the minimum amount of information you can capture in the document that would serve as a reminder for a future conversation?

Is the document for now or later?

If the document is required now, consider simplifying or replacing it with a conversation, white board pictures, paper prototypes, code snippets, or brief videos summarizing decisions. If the document is for later (ex. User guides, regulatory, help manuals etc), then consider creating it at a future time. Also check how often do people actually use the document.

Who is the audience for this documentation?

Check with your stakeholders who use the document about the required set of information that is sufficient for them.

What is the business value of this documentation?

If it has little value, then it doesn’t need a lot of information. If it has a lot of value (like a required regulatory document), then make sure the level of detail accomplishes the required value and no more. Why are we producing this document? Would you pay someone to create this document? Is it worth the investment?

Is this information available through another means?

Instead of manually creating documents such as API, SOA documents, consider using some tools available to create these documents automatically. Instead of sharing a HLDD (High Level Design Document) to someone, create a lego based architecture with minimal documentation.

Is the purpose of the document to detail requirements or design in depth?

There is always the possibility of requirements changes on our projects, capturing this level of detail up front may lead to rework and waste of effort. So instead, you can have focus group discussions, interviews and surveys.

Can I specify the content in an automated test format?

Using Acceptance Test Driven Development or Behavioral Driven Development, promotes writing your requirements as automated test cases. This allows you to have an executable yet readable specification that is developed throughout the project in collaboration with your stakeholders and the development team. 

How should I create the content for this document?

Consider creating the content using inclusive models. It helps others to easily contribute as in creating the content of the document using tools such as: post-its, and whiteboards. A 100 page microsoft word document is not an inclusive model, because if you ask someone to give feedback on the document, you are more likely to get grammar and formatting edits than suggestions for improving the content.

Is this document so heavy and hence no one will have interest or time to read it?

Large documents create ambiguity and disinterest in people to read them. So find a better way to create interest and to get some value for the content.

Document Stable things .. Not speculative things

Do not jump on to create documents before things get confirmed and without ensuring it is really needed to document.