As teams have moved from waterfall to agile ways of working over the last two decades, a negative stigma has formed around documentation. 

Many teams have misinterpreted the Agile Manifesto's declaration of “working software over comprehensive documentation” to mean “no documentation.” While it’s true that traditional approaches to documentation are inefficient, eliminating documentation altogether can be harmful to agile teams, particularly as remote and hybrid work becomes more common. 

Consider trying to build a house. It doesn’t matter how fast, incremental, and efficient you are, if you never do your framing and foundation work, the house won’t stay standing for long. Similarly, documentation provides agile teams with the foundation needed to learn, adapt, innovate, and deliver value to customers. Without it, agile teams are misaligned, prone to error and miscommunication, inefficient, and lack the context needed to make decisions and adapt to market changes. 

In other words, while eliminating documentation may seem like a way to increase agility temporarily, it actually significantly decreases agility in the long run.

Rather than getting rid of documentation altogether, teams are faced with an opportunity to create better documentation. The solution isn’t going back to how documentation was approached in the waterfall days—teams need to embrace documentation that’s organic, living, adaptable, and highly visual.

What does an agile approach to documentation look like?

An agile approach to documentation follows many of the same principles as the Agile Manifesto itself. That is, it should be iterative, adaptable, and collaborative. The goal of effective agile documentation should be to:

• Better share context among teams and eliminate unnecessary back-and-forth.

• Enable teams to go to market faster by templatizing repeatable processes.

• Create an efficient onboarding experience for new hires.

Given the growing complexity of business—there’s more software, more data, an accelerated pace of change, and the increasing adoption of distributed work—organizations can’t afford to forgo documentation. It’s a necessity to work efficiently and innovate continuously.

“In today’s world, the ability to do the simplest thing that works and develop small increments of working software that delivers something of value matters more than ever. I don’t believe that comprehensive documentation is what keeps teams aligned. Rather, clarity is what keeps teams aligned—clarity about the vision of the product, clarity about the problem we’re trying to solve, clarity about the value being delivered, and clarity about what the team needs to be successful. When there are inevitable tensions between working software and comprehensive documentation, it’s helpful to remember to do the simplest thing that works. And to embrace change.”
—Heidi J. Musser, board member, board advisor, and executive consultant

And as organizations face tightening budgets, employee turnover, and other threats to their businesses, better documentation helps prevent valuable knowledge from slipping through the cracks.

What are some examples of agile documentation? 

Agile documentation involves documents, diagrams, or templates that are simple to understand, highly visual, and help teams make decisions and move forward. This can include:

• Product backlogs

• Burnup and burndown charts

• User story maps

• UML diagrams

While these are important documents for keeping teams aligned, there are also less formal ways of documenting information that are just as important for continuous innovation.

For example, If you host your Agile events remotely, use a virtual team room to capture ideas, roadblocks, or feedback. This virtual space acts as a form of living documentation that provides a record of project context and decisions.

The dos and don’ts of Agile documentation

With all this in mind, here are some tactical tips for approaching agile documentation:

Do: Document continuously as you work

A common criticism of documentation is that it’s an intensive process that takes time away from actual coding and product development work. It doesn’t have to be, though.

 An InfoQ article suggests an approach to continuous documentation that relies on coupling your documentation to your code and producing documentation “when best.” For example, you could create documentation immediately after a bug fix instead of at the end of a large project.  

Another approach to continuous documentation is creating an innovation repository by turning all the broader brainstorming, planning, and execution work you’re already doing into a “living blueprint” of how your business brings its best ideas to life.

Thinking about documentation this way makes it a natural extension of building, coding, launching, and monitoring—not a separate chore you do begrudgingly. It’s also more efficient to document as you work because you’re able to make process notes while they’re still top of mind.

Don’t: Create documentation for the sake of documentation

Throughout the process of creating continuous, agile documentation, it’s important to ask yourself the following questions to avoid creating documentation for its own sake:

• What is the purpose of this documentation?

• Who is this document for, and how will they use it?  

• Does this document already exist elsewhere?

Adopting a mindset of continuous documentation doesn’t mean you need to do redundant work. Rather, you should be looking for opportunities to add to and improve existing documentation wherever possible.

“The point is to have a place to collaborate—a place where we can build elements that help define how we’re producing the product.”
—Jon Kern, co-author of the Agile Manifesto

Addressing versioning issues, optimizing a hard-to-find or hard-to-read piece of documentation, or adding screenshots and diagrams to a text-heavy piece of documentation are all important ways you can impact your company’s knowledge base beyond creating new documents from scratch.

Do: Look for opportunities to automate when possible

Adding data linking and other integrations to your documents can reduce errors and mistakes that come when you have to update documentation by hand—especially for entity relationship diagrams (ERDs) or other documentation showing complex data relationships. 

Automation can also help you save time and manual labor by refreshing key portions of your documentation without you even thinking about it (or knowing it's happening). Having the newest data at your fingertips rather than having to hunt for it can help you better generate actionable insights and uncover patterns you otherwise might have missed.

Don’t: Wait until the end of your project to document

Waiting until a project is over to document carries the risk of forgetting information, introduces more room for error, and adds an unnecessary burden at the end of a long sprint when the enthusiasm to do “one more thing” will likely be at its lowest.

Jim Highsmith, co-author of the Agile Manifesto, says, “Include documentation as a part of your sprint tasks. This ensures that documentation is treated as part of the definition of done for new features or updates.”

By approaching agile documentation from the perspective of building an innovation repository in the moment and over time, documentation becomes embedded as a natural part of the project—from ideation and planning to design and launch—rather than a tacked-on task.

Don’t: Produce documents in a silo

It’s inefficient to spend time creating documents individually, and then only gather feedback when you’re well into a draft. If the scope of your documentation is off, or critical details are missing, you’ll now have to spend time on a major rework that was completely avoidable.

Involving others early on to find out what documentation is actually needed—or by collaborating on the documentation itself—will save you time and pain later.

Do: Create documentation collaboratively as a team

Documentation doesn’t have to be a solo endeavor, especially when you’re building your documentation from code, brainstorm boards, planning maps, or other documents you’ve already created together as a team.

Involving others in the documentation process ensures their awareness and buy-in. It also creates  collective accountability to make sure team documents are kept up to date. For newer or more junior employees, being involved in the documentation creation process can also be a good learning experience.

One of the biggest pain points with documentation is how frequently it has to be updated and how much communication and distribution work needs to happen to make sure everyone is aware a new version is available.

Using a cloud-based storage option—preferably one that accommodates visual collaboration in order to make information even more understandable—means you don’t have to deal with versioning issues and ensures team members have access to the information they need to make decisions quickly and confidently.

Don’t: Use documentation to replace conversation

While clear, visual documentation can enable asynchronous work, it should supplement conversation, not replace it. Creating better documentation isn’t about eliminating the need to collaborate with team members—it should make those connections stronger and inform conversations that lead to breakthrough thinking and innovation.

Remember this Agile principle: The most efficient and effective method of conveying information to and within a development team is face-to-face conversation. For hybrid teams, this could be as simple as jumping on a quick Zoom call. 

Do: Use engaging and simple visuals

Documentation that prioritizes visuals over just text helps you clarify complex information, show relationships between entities clearer, and is more easily digestible at a glance for stakeholders.

Imagine joining a new company only to find out that sprint plans are shared in Google Docs or Google Sheets only. While a bit of an extreme example, the same principle applies to using visuals for any kind of documentation. Clear visuals save the reader from having to do work to understand complex structures, relationships, and dependencies, freeing up their time to focus on actual job responsibilities.

Don’t: Create overly dense, text-heavy documents

In an attempt to be thorough with documentation and get your thoughts down, it can be difficult to remember that you aren’t necessarily writing the documentation for yourself. If you’re writing for yourself versus everyone else, you may glance over important steps, miss glaring information gaps, or bury important information in a dense wall of text.

The problem with this is you’re often left with a document that might make sense to you—because you have expertise and context on the process—but is inaccessible to others.

If you find documentation is regularly taking a lot of time to produce, it could be because you’re being too verbose. If documentation is so dense that it’s not clear and goes unused, it’s not good documentation. Simpler is often better.