I've been thinking about documentation in Agile for a long time, but only recently have I thought about what Agile documentation development itself might look like. Organizations have adopted Agile for its ability to empower teams to create high-quality products faster. From that angle, I wondered whether a documentation team might see some gains by adopting "docs Agile."
To clarify, I'm not talking about including technical writers on Agile teams (although I’ve written about it in the past). Instead, I'm doing a thought experiment to see what the Agile Manifesto would look like if, instead of being applied to development teams, it applied to documentation teams. I’ve tried to keep the docs team incorporated with development and testing during my thought experiment. Overall, I think these ideas are instructive in terms of what writing teams can do within an Agile framework.
Because I have a lot of thoughts on this topic, I’ve broken it up into two parts to make it easier to read. If you can’t wait, though, you can download a copy of the full article as a PDF.
Agile Manifesto Refresher
As a refresher, here are the 12 Principles of Agile Development:
Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.
Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.
Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.
Business people and developers must work together daily throughout the project.
Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.
The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
Working software is the primary measure of progress.
Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely.
Continuous attention to technical excellence and good design enhances agility.
Simplicity – the art of maximizing the amount of work not done – is essential.
The best architectures, requirements, and designs emerge from self-organizing teams.
At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.
So what would these mean if we translated them to a docs team?
#1: Our highest priority is to satisfy the customer through early and continuous delivery of valuable documentation.
Under this principle, writers release documentation on a continuous basis, reflecting the continuously released software. To achieve this, the writing team has access to information about new functionality and the ability to document that functionality.
In terms of information about new functionality, access to the finished software itself is the obvious choice. However, waiting for completed development means the writer must lag behind. To avoid the lag, writers need access to high-quality development artifacts such as user stories. This kind of access is enough to get the docs ready for a customer testing group or UAT.
In fact, the "early and continuous delivery" part of this principle isn't what intrigues me; instead, it's the focus on customer satisfaction. Although documentation exists as a concession to customer satisfaction, we don't often think about customer satisfaction with regards to the docs. What does that look like? What does the customer want from the docs? What would make that experience even better?
Taking another page from Agile practices, the solution is to release what's available to the customer and iterate on it. For example, as part of an initial release, it might make sense to release a PDF guide just to get working docs out the door. But rather than rest on that, the business, development, and writing teams work with them to tease out the customer’s documentation preferences. Perhaps they want help integrated into the software itself, or an online help portal. Perhaps they're satisfied with the PDF, but find the organization of its topics confusing or not closely matched to their process. All this is good feedback that the docs team can use to iterate on documentation delivery.
Another consideration is docs UAT during the regular UAT cycle. This doesn’t add a significant lift for the customer or development team, but pays huge dividends in documentation feedback. In the same way that development UAT shakes loose bugs that can be resolved in future iterations, a docs UAT can perform the same function, highlighting the areas of the documentation that aren't working as expected (i.e., are confusing or wrong) or which need improvement.
My final consideration from this principle goes back to the "early and continuous" portion of the priciple. If we're truly planning to release software – and therefore documentation – on a continuous basis, the training need on the system can quickly become overwhelming. I've experienced this overwhelm firsthand with a client who requested several custom development upgrades to our standard software offering. This client had hundreds of users accessing the system each day to perform work on a highly complex and legally challenging process. Within about 10 iterations, the training lift had become too much to bear, and they asked us to put off user-facing updates. Although this was a good time for the development team to fine-tune the backend, I wondered at the time what could have been done to slow or prevent that training overwhelm. Perhaps more direct access to me as their technical writer and a culture of providing feedback on both software and docs would have led to novel solutions to this problem.
#2: Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.
I'll confess that I chuckled when I thought about this principle in the context of documentation. I've been writing professionally for nearly 15 years and changing requirements – even late in development! – is the name of the game. Although writers with less professional experience might struggle with this, seasoned professionals will roll with these types of punches with nothing more than a resigned sigh.
That said, it's always preferable to reduce rework if possible. To that end, it's important not to begin writing until there's a clear user story for the functionality that’s been groomed by the team and added to the current sprint. Although requirements may change, this practice – and the practice of sharing user stories with the docs team – will keep rework to a minimum.
#3: Deliver working documentation frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.
This principle seems straightforward: keep the documentation updated to reflect current functionality, and release it frequently. But I'll go a step further. If I rewrote this principle to reflect its spirit, I would write "Deliver working documentation frequently alongside the functionality it describes."
A small but vocal minority advocates for leaving documentation behind during the development process. When I worked in Waterfall development, this meant the writer had access to requirements but nothing more. Considering the lack of specificity as to final layout of the product, as well as the disconnect between requirements and final development that often occurs in Waterfall development, they weren’t helpful. To make matters worse, my team was also often cordoned off from development and testing, making it nigh impossible to access to our SMEs until the last possible minute. Sadly, this seems to be de rigueur in organizations that use Waterfall development.
Despite this total lack of access, leadership demanded that documentation be ready for release at the exact moment the code was. Our pleas to have time after code complete to systematically document the completed system were ignored. The result was that we sat on our hands for months until there was a working system in QA, at which point we scrambled to get what information we could from the system and SMEs. The system would shift beneath us without notice. Right up to release day, we laboriously combed through the system to find updates, praying we hadn't missed anything. If we had significant rework and missed our date, the release went forward and the users had nothing to help them use their new product.
This is not an effective way to get high-quality documentation. And yet some Agile practitioners think it would be better to send the technical writers back into this stone age. They believe it’s acceptable to release without documentation. They are wrong. They believe release notes are documentation enough. Unless there are no user-facing updates, this is also wrong.
From a user perspective, the documentation is the step between not understanding the product and understanding it. From a business perspective, the documentation is the step between the user not understanding and the user calling support. Although there will always be a contingent of users who reach out to support first, good documentation can greatly reduce support and the costs associated with it. If you don't have support, documentation becomes even more important as the only support offering.
If your customer doesn't understand how to use your product, they won't use it at all. This is doubly true if they search and no docs exist, or if the only docs available are outdated or wrong.
To avoid your customer giving up in frustration, current and correct documentation is essential. There’s no excuse for releasing software and documentation out of sync.
#4: Business people and writers must work together daily throughout the project.
Considering my experience in Waterfall environments, where the only interaction I had with the business was them delivering the requirements doc, you can probably guess my thoughts. In the same way that it's imperative for the development team to maintain close contact with the business, it's imperative for the docs team to do the same. The docs team needs the same kinds of insights as to customer requirements, feedback, and so on.
Under this principle, the documentation team is included in team meetings with the business, at a minimum. This includes backlog refinement, sprint planning, and sprint review meetings. If your organization has other meetings that include the business perspective, the documentation team is included there as well.
In a similar way to development, the documentation team uses these interactions with the business to not only listen to what the business needs, but also to help the business understand its own limitations based on budget, access to an appropriate tool, or other concerns. The business provides or advocates for the writers' needs and offers clear requirements. In turn, the writers provide the best documentation they can to meet the business's stated needs.
#5: Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.
Under this principle, the business builds teams from individuals who are motivated, using trust to build that motivation.
This item also got a reaction out of me, but not the chuckle I had with Principle 2. Another common sentiment in the industry is that writers can't be trusted. This hasn’t just been applied to me; I've seen it applied to writers with vastly more experience and across multiple teams and organizations.
I suspect it's a symptom of the problems I experienced in Waterfall: writers aren't given the resources they need, leading them to either pester development (who shouldn't be on the hook for providing good information) or waiting to write until the last possible second to avoid rework, slowing down the final release date. Because both are unwelcome outcomes, the team's trust in the writer erodes despite that the writer didn't create these failure conditions.
If you're releasing software that's intended to be used by humans in any fashion, documentation is necessary. The writer doesn't exist to slow down the team or hamper development, but to provide a valuable addition to it. When the writer has what they need, they can deliver on time as easily as a developer. But in order to get what they need, the business needs to trust that the writer is here for the team just as much as any other team member. They need to trust that when we ask for more information, it's not to cause trouble but to prevent trouble down the road. The business – and the team – needs to trust that the writer is a professional and wants to do their job to the best of their ability.
#6: The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
Under this principle, the writer is co-located with the team in order to facilitate face-to-face conversations with them. Ideally, the team is also co-located with the business. If it's not feasible for the writer to be co-located with the team, they at least keep close contact through daily meetings, including the daily scrum.
You'll notice that I didn't replace "development" with "writing" for this principle. This is because the "development team" includes more than developers, and should ideally include the writers on the project as well. By integrating the writer with the larger development team, you can benefit from the face-to-face conversations promoted in this principle to help the writers more quickly and easily understand the direction of the sprint and the pace of development. They can also share their roadblocks, help clear the roadblocks of others, and glean the information they need rather than having to pin down specific team members with their questions. This is also one of the reasons it's extremely valuable to include writers in grooming sessions.
That said, this principle can also be narrowed to focus on the documentation team specifically. In this reading, the docs team members are co-located to facilitate face-to-face conversations. Although each writer may not necessarily work on the same project, the benefit here is in the ability for the team to standardize their processes, style guides, templates, and other team-level assets. When each writer is aligned on these points and can provide dynamic feedback to the team about their successes and struggles, they can improve the overall effectiveness and branding of the documentation.
Another advantage is that if one writer becomes overwhelmed by the work on their specific project, they can quickly pull in other writers who can flexibly support them. Writers will also benefit by being close to others who can QA their work from the perspective of grammar and style adherence without the need for other team members to learn extensively on these points. As implied by the principle, co-location isn't critical, but it helps.
Want to learn more about docs in Agile? Check out my eBook, “The 12 Principles of Agile Documentation.” Learn how the original 12 Agile principles apply to documentation, how to change your thinking to accommodate documentation, and the benefits you can get from bringing the docs into the fold.
