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.
