Agile teams are becoming more and more common in software development, and it makes sense: the methodology lets you get your customer's feedback fast and iterate quickly on that feedback. But as teams embrace these principles, one important deliverable is often overlooked: documentation. Some Agile practitioners don't consider the technical writer part of the Agile team at all, but this approach is short-sighted. The software needs to ship with docs, and it's frankly unprofessional to do otherwise. You could hold off releasing the product until you can hire a writer to appropriately document it (delaying your release by weeks or months) or allow the writer to join the team, develop their work as part of it, and release alongside the product.
Documentation isn't impossible in an Agile environment; indeed, it’s a lot easier! Avoid these 5 common pitfalls to get the most out of the writer on your Agile team.
Divorcing documentation from the sprint cycle
If you're accustomed to a Waterfall approach to docs development, you might be surprised to learn that writers can write in time with a sprint cycle. Although some places have the writer lag a sprint behind, I don’t think that’s necessary for many teams. The biggest consideration is whether you have enough writers on the team. I’ve gone into detail about how to estimate the number of writers you need, but in my current position, a 3:1 developer-to-writer ratio on a 2-week sprint cycle feels comfortable. I’ve been writing as part of an Agile team for over two years, and I’m convinced that whatever a developer can put together in two weeks, the writer can document in the same time frame.
Restricting writer access to user stories
Although I confirm my work against the test system before publishing, I don’t need a completed screen to do my work. If the story is clear enough for a developer to develop it and a tester to test it, it's almost certainly clear enough for a writer to write it. Indeed, a screen alone is less helpful, since it lacks the context and user information recorded in a user story. With that additional context, writers can write higher quality docs faster.
Caveat: if the writer is playing catch up to document weeks or months of development, it’s faster and more effective to do Waterfall docs development until they catch up with the rest of the team. Although it’s hard to catch a moving train, it is possible with the right ramp-up.
Excluding the writer from meetings and ceremonies
If you use Scrum, you might have heard the old chicken and pig chestnut: A pig and a chicken decide to open a restaurant together. When thinking of names for the restaurant, the chicken suggests “Bacon & Eggs.” The pig refuses, saying “You'd be only involved, but I'd be committed!” This story explains the difference between people who are committed to a project’s success versus those who are only involved in it. This rationale also is used to gatekeep who can and can’t participate in meetings.
Technical 👏 writers 👏 are 👏 pigs.👏
Tech writers aren't just involved in the sprint or the release; we’re committed. Writers create an essential component of the overall product: the documentation. Practices that ostracize writers from the team and team meetings serve to encourage a Waterfall approach to documentation; it’s just another kind of “AgileFall.” You're only hurting yourself by leaving the writer out of the loop.
The writer should participate in any team meetings and ceremonies a developer would: daily stand-ups, backlog grooming, planning meetings, retrospectives, and so on. Although the writer probably doesn’t need to point stories (I get by fine by creating tasks on stories) it's important to see what's coming down the pipe, to help groom stories to make them easier to document, and to show that they’re part of the team.
Bypassing docs QA
The writer is just as fallible and human as anyone else on the team – we make mistakes too. And just like errors and bugs in the code, errors and bugs in the documentation can lead to poor outcomes for your users. One of the worst customer experiences imaginable is having a problem, looking at the help, and discovering that the help isn't helpful. Or worse, that it's outdated and just plain wrong.
You can avoid this with a docs QA step. Although I personally prefer feedback from the entire team, robust feedback from just the product owner or major stakeholders is fine too. Feedback in hand, the writer can ensure your customers have the best outcomes possible. You wouldn't release untested software to your customers; documentation deserves the same rigor. Don't let errors propagate in the docs – make sure you QA the docs.
Leaving documentation off the DoD
As I said above, we're creating an essential component of the product: documentation. Because docs are essential, the product isn’t done until the docs are done. This means putting the docs on the Definition of Done (DoD). You might fear this will only slow down the team, but if you’ve given the writer the resources they need, they can easily keep pace with development. This includes everything above: inclusion in the sprint cycle, access to user stories, invites to the meetings, and feedback during docs QA.
Some of these suggestions are big changes. They'll take a lot of cultural change, and change can be painful. You'll probably get a lot of pushback from people who are afraid that letting the technical writer in will disorient the team, slow the velocity, and derail the meetings. But if you can make these changes and bring a writer in, you'll be astounded at the improvements to your documentation products, both in speed and quality of delivery.
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.
