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 haul.

Rather than getting rid of documentation altogether, teams are faced with an opportunity to do documentation better. 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 hybrid teams and eliminate unnecessary back-and-forth
• Allow teams to go to market faster by templatizing repeatable processes
• Create an efficient onboarding experience for new hires

Given the growing complexity of business—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.

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

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
• Burn up and burndown charts
• User story maps
• UML diagrams

While these are important docs 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 do’s and don’t of Agile documentation

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

Do: Document continuously as you work

Much of the gripe with 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.

A recent InfoQ article posits an approach to continuous documentation that relies on coupling your documentation to your code and producing documentation “when best”—which could be immediately after a bug fix, for example, instead of just in the aftermath of a large project. And Lucid’s own writing on innovation repositories suggests an approach to 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 the building, coding, security, testing sales, and marketing process—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 it’s still top of mind.

Don’t: Create documentation for the sake of documentation

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

• What is the purpose of this piece of 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.

Addressing versioning issues, optimizing a hard-to-find or hard-to-read piece of documentation for ease of discovery and readability, 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 just creating new documents from scratch.

Do: Look for opportunities to automate when possible

Adding database and other integrations 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 only 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 enthusiasm to do “one more thing” will likely be at its lowest.

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 at the end.

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 through discovery interviews 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 with 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 process ensures their awareness and buy-in by making it a collaborative process. It also creates a collective accountability to making sure your org is rigorous about documentation, which reinforces the importance of keeping documents up-to-date as a team. For newer or junior employees, being involved in the creation process can also be a very sticky 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 a 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 washing your hands of the need to collaborate with teammates—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.

Do: Use engaging and simple visual elements

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 their org chart is written entirely as a bullet point list. There’s no hierarchy or levels or lines showing reporting structures, just a list of names and job titles—and you’re left to do all the heavy lifting to understand the relationship between different individuals and teams.

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 brain on paper, 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 tend to 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 for someone attempting the process for the first time.

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 better.