Agile documentation in the real world

In Agile documentation in practice I described what worked for me, which works, when it works, but it’s not without its challenges. However, if you can get these right, the process should be smoother.


First and foremost, it works best when everyone is on the same page. When stakeholders have different ideas of quality, content, scheduling, iterations, or priority, things become difficult. This should come as no surprise, but it’s worth repeating because without a common understanding of the ground rules by all the stakeholders, those disagreements complicate all of the other areas.


In Agile documentation in practice, I mentioned how the traditional writing process was not what worked for me in an Agile shop. When I matched my writing process to the coding process as much as possible, things became easier. Once I was able to plan and describe my process in terms that made sense to agile software developers—something that I couldn’t do until I embraced the process for myself—it was easier for them to understand what I was doing (and when I was doing it).  Reporting progress clearly and frequently is an essential part of a successful process (Agile or otherwise).


A big part of the process consists of the tools used to execute the process. Agile is designed for changes. Changes in requirements. Changes in features (content, for documentation). Changes in audience. To name a few. The tools used to manage the workload and the content must accommodate the changes you want to accommodate as easily as possible.

Which tools are best? That depends on your process (and is worthy of a topic or two in itself). Ideally, the process will define the tools, not the other way around. In reality, however, this is often difficult to apply in practice. At least, with a clear process, you’ll know what your tools will need to do.


Collecting and analyzing data must be integral to the process. Data such as audience requirements, product road map, market climate, at the high-level and direct customer feedback, usage and satisfaction metrics, and production metrics at the detailed end, to name a few. Without a constant calibration, the writing process becomes increasingly disconnected from reality—and remember, reality is a moving target, which is why you need to keep your data up-to-date.


If you’re an Agile shop, this shouldn’t be a problem you can’t handle because the sprint planning process takes this into account. Each sprint has its velocity (capacity) for development tasks and it will also have its velocity for technical writing. This always begs the question:

What is the right ratio of developers to writers?

It depends, of course. But if you have all of the above, you might not have enough writers to produce everything you want to deliver, but you’ll have the process to do the best you can with what you have and the data to know if you need more or fewer.

Leave a Reply