There is a recurring myth in the IT industry that Agile projects do not require documentation, that giving stakeholders the opportunity to respond to fully functional software replaces that need altogether. This perception (or, more accurately, this misperception) often stems from a misunderstanding of the following statement in the Agile Manifesto (https://agilemanifesto.org):
” We have come to value…. Working software over comprehensive documentation”
The creators of the Agile Manifesto have clarified this statement numerous times, emphasizing the following qualifying condition at the end:
“That is, while there is value in the items on the right, we value the items on the left more.”
In effect, they are not saying that documentation is unnecessary for software delivery; they are simply saying that the review of working software in an interactive environment is a more effective way to confirm user requirements than having stakeholders read through stacks of two dimensional written specifications.
This article endeavors to take this clarification one step further. The statement above refers specifically to solution requirements documentation not to all of the other documents that almost every software development project needs to provide regardless of the selected delivery method. Whether your project team follows an Agile method, a waterfall approach or a hybrid model, there are seven types of documents that your team will most likely need to produce:
- Contract Deliverables:
If your project is being delivered through a contract, there will inevitably be documentation deliverables that your team is required to produce to fulfill the contract scope. Using Agile methods for software delivery does not release you from these obligations. Unless you are fortunate enough to have a contract that is designed around Agile methods, or you can arrange for a contract amendment that allows you to provide working software in lieu of solution documentation, your team will need to provide these documents even if they are not essential in the delivery of your Agile project.
- Project Plan:
Every project needs a documented plan, a shared vision that the team can work toward. Whether your project plan is:
- A combination of Epics and a Product Backlog that changes as your solution evolves, or
- A more formalized plan to communicate your project goals with others in the organization
this vision needs to be documented, shared and adapted to ensure that your project work aligns (and continues to align) with team and stakeholder expectations.
- Solution Requirements:
This is, arguably, the one type of documentation where Agile teams have the flexibility to determine the minimum amount required to achieve project goals. Even with this flexibility, however, it is rare to find an Agile project that does not have some degree of written requirements documentation including supporting details for User Stories such as defined field values, complex algorithms, and other descriptive information that is not easy to share through face to face communication. The key difference is that waterfall methods rely on written documentation as the primary communication tool; Agile method use documentation to supplement more effective methods of communication.
- Compliance Requirements:
If your organization is required to comply with mandated requirements including legislative, industry, or quality management certification standards, your project team will need to produce the minimum project documentation needed to fulfill these requirements. The one exception may be more forward thinking organizations who design their quality management programs to include Agile artifacts as evidence of compliance.
- Written Approvals:
Even when a project deliverable is verbally accepted by the Customer in a Sprint Review session, it is essential that the project team supplements that stated agreement with written documentation of the Customer approval. Having this confirmation in writing is the most effective way to protect your team and your organization from disputes, especially where there is a risk of the organization having to absorb the cost of future changes. For some organizations, this documentation can be as informal as a follow up email that confirms their stated approval with an explicit due date for the Customer to reply if they do not agree. For other organizations, this approval needs to be more formally documented to fulfill contractual, compliance, or financial auditing requirements.
- Production Support Documents:
Regardless of how your solution is delivered, once the software goes into live use, there is a need to provide your production teams with sufficient documentation to be able to effectively support that solution. This may include creating technical support manuals, troubleshooting guides, systems administration guides, integration specifications, or even retrospective design specifications to assist the teams tasked with the ongoing development of the solution. On most Agile projects, the working software that the team produces can be used to create as built support guides to minimize the time required to develop these documents.
- User and Training Guides
No matter how intuitive your solution is, it is almost inevitable that you will need to produce some form of documentation to help the initial (and future) users navigate through the solution. This guidance may not necessarily take the form of printed materials. Online help, training videos and interactive tutorials could equally serve this purpose (and may help you think of what you are delivering as technically not documentation!)
Advising you of the required documentation on Agile projects is not intended to diminish your excitement in using these methods. Exactly the opposite. It is intended to give you advanced notice to allow your team to plan for the time required to produce these documents and, if needed, arrange for technical writing support. This minimizes the likelihood of unexpected commitments at the end of the project and establishes shared expectations for all stakeholders, including the Agile team.
