People sometimes believe “It’s agile, so there is no documentation” or “Agile is anti-documentation.” Neither of these statements is correct. Instead, the incremental and iterative nature of agile software development brings an opportunity to create, leverage and improve documentation in new and refreshing ways that bring new value to projects and stakeholders.
This article identifies the various types of documentation used for agile projects and why they are approached differently than traditional projects in information system engineering.
The Manifesto for Agile Software Development states that “we have come to value working software over comprehensive documentation.” This statement is sometimes interpreted as agile is anti-documentation. However, the sentence included after the four values provides clarity not often discussed: “That is, while there is value in the items on the right, we value the items on the left more,” In other words, there is value in documentation, and there is more value in working software. This is a statement about priorities and focus. It does not suggest one should apply sole focus on working software and ignore documentation.
To expand further on this thought, one of the 12 principles of the manifesto states, “Simplicity, the art of maximizing the amount of work not done, is essential.” Developers strive to keep projects as simple as possible to avoid waste due to unnecessary complexity. Just enough documentation should be generated to execute the project effectively and efficiently without crossing the line into excess, which leads to waste.
This is explained through the law of diminishing returns. The incremental benefit of documentation needs to be evaluated and used to gauge the appropriate amount required. After evaluation, if there is benefit to the project by having more documentation, then it should be provided. However, if the incremental documentation does not provide incremental value to the project, then it should be viewed as waste and be eliminated. No two projects are exactly the same, so the amount of documentation will vary.
Documentation can benefit projects by providing clarity, obtaining feedback and simplifying a complex idea. Each of these benefits lead to simplicity and help the team reach its goal – working software –faster.
How agile documentation differs
Agile documentation exists, however the agile mindset and approach are different from traditional projects. In scrum, which is one of the various frameworks under the agile umbrella, there are concepts like product and sprint backlogs, releases and retrospectives, to name a few. Each of these concepts is used for specific purposes and situations. Backlogs organize and prioritize upcoming and current work, releases provide visibility into plans of upcoming work, and retrospectives check on team performance and identify areas of improvement on a regular basis.
Agile projects do not use the “one-size-fits-all” approach for documentation. The types of documentation differ from project to project based on what is needed to deliver a successful product. A good analogy is a handyperson loading tools into their toolbox for an upcoming job. They would only load the tools needed for a job instead of loading all their tools into the toolbox. If the handyperson loads all their tools into the toolbox, they add clutter that may result in hiding the ones with higher benefits and project value.
Some examples of documentation within scrum include;
Product backlog – describes the features, and requirements of the product being built
Sprint backlog – a subset of the product backlog that receives the highest priority during a sprint
Release plans – provides visibility into the planned delivery of features over time
Retrospective notes – insights and activities used by the team for continuous improvement
Burn charts – provides visibility to team progress by showing work completed and work planned
Task board – provides visibility to progress during current sprint
Other examples of documentation to be used as needed to fit the situation. Many of these are used in more traditional projects as well.
Use cases – description of actions taken by actors/roles in the system
Persona – fictional character that represents user types that use a system in a certain way
Context models – describes the context in which the system operates; users, environment, actors
Data models – defines how data interact with other data in a system, describe business rules
State diagrams – documents complex business rules and change from one state to another
Human-centered design methods – Buy A Feature, What’s on Your Radar, Affinity Diagrams
Conclusion
Having the right amount of documentation is important to both traditional and agile projects for alignment, decision making, planning and sharing information. Selecting the types of documentation will depend on the type of project methodology used and the unique needs of the project and project stakeholders.
Matrix Technologies is one of the largest independent process design, industrial automation engineering, and manufacturing operations management companies in North America. To learn more about our manufacturing operations management capabilities and executing projects using the agile software development, contact Jeff Panning, PMP, ACP, Senior Project Manager, Project Management Professional, Agile Certified Practitioner.
