Benefits of agile documentation for projects

Agile software development brings an opportunity to create, leverage and improve documentation in ways that bring new value to projects and stakeholders.

By Jeff Panning, PMP, ACP January 28, 2022
Courtesy: Matrix Technologies

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 ways that bring new value to projects and stakeholders.

The manifesto for agile software development has four key values about improving value through developing software. Courtesy: Matrix Technologies

The manifesto for agile software development has four key values about improving value through developing software. Courtesy: Matrix Technologies

The manifesto for agile software development states: “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 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.

– This originally appeared on Matrix Technologies’ website. Matrix Technologies is a CFE Media and Technology content partner. Edited by Chris Vavra, web content manager, Control Engineering, CFE Media and Technology, cvavra@cfemedia.com.

Original content can be found at Control Engineering.


Author Bio: Jeff Panning, PMP, ACP is a senior project manager at Matrix Technologies. Jeff is responsible for the successful completion of manufacturing and operations management projects.