10 Things That Suck When Writing Documentation in Agile Development: Part 1

Every software company has an approach to writing documentation. It typically builds on the way the product development works. Some of them are really unique; some of them apply what the book says. But no framework and way of working are perfect. What problems does agile development bring to the docs? In this part, I’ll focus on Technical Writers’ workload and priorities.

How Did We Get Here?

Kentico, a software (CMS) vendor, started with the waterfall approach as many companies did. In the early 2010s, we switched to agile development. You can imagine Scrum teams of five to seven Devs and Testers, a Product Owner, UX Designer, Scrum Master, and — you’ve guessed it — a Technical Writer. The typical setup.

Over time, we’ve noticed some unpleasant things that have kept happening. As a manager of Technical Writers, I was often thinking about how to overcome the issues we experienced. For each thing that sucks, I’ll briefly touch on how we’ve addressed or at least tried to address it.

No framework is perfect, but you can minimize its drawbacks. Or die trying :)

I’ll try to keep this list general, so I won’t get into specific downsides of switching from a particular framework. My opinion on switching a way of working is that the downsides are often based on fear of change until you’ve tried it. This list should apply to anyone creating the docs within agile development regardless of how they worked before.

#1: Focus on the Features

The more you’re integrated into a dev team, the more you start thinking like Devs in the team. That brings many advantages, like a more in-depth technical understanding of what’s created. However, one of the reasons why Devs don’t usually produce the same level of documentation quality as specialized Technical Writers is that they’re too deep in how the machine works. Which method does what in which class.

Devs may be the best in developing your product, but it’s a Technical Writer’s job to think like a customer. Staying too long with Devs steers you away from this kind of thinking.

Devs program features and features you’ll describe.

In this way of working, Technical Writers rely on the dev team’s user stories. When Devs know why they’re doing something, Technical Writers know it better too. That’s why we tried to push the dev teams to produce better user stories. We also invested some time into talking to our support, reading customer cases, and watching customer interviews. Both activities have only partially solved the problem, though. Even with repeating ourselves to describe scenarios, we often described features instead.

#2: Uneven Sprint Workload

If you’re working in sprints, as you do in Scrum, for example, you’ll notice that the two weeks differ very much. It starts with the Devs. The first week, they start and are pretty relaxed. The second week, they worry that they won’t manage to finish the sprint in time and work as quickly as possible. It’s not a wonder; pretty much everyone would do this the same way.

Technical Writers usually adapt to this quickly. What it means, though, is that you don’t have anything to write about the first week. And you work like crazy the next one. This disproportion repeats almost every sprint.

To overcome this, we were trying to start writing the docs right from the beginning. We were writing as if the new functionality was done right at the beginning. A part of the job can then be done earlier.

We also tried to arrange that we would release the docs after the sprint closed, so a shifted sprint by a couple of days or even a week. But this is against the typical Scrum best practices, so we didn’t really have the chance to thoroughly explore this option.

#3: Uneven Feature Workload

Going a level higher, it’s not just individual sprints that are uneven. Look at the epics (or whatever term for big chunks of functionality you use). For some of them, the Dev effort matches the Technical Writer’s effort. However, there’s also a big pile of those epics that:

• Take multiple sprints to implement, but they’re just a couple of lines for you.
• Devs deal with in one sprint, yet they mess with a lot of docs, and you spend a month fixing it.

Which Technical Writer didn’t have to, at least once, rescreenshot half of the documentation after a Dev innovated something one afternoon?

Development Effort ≠ Documentation Effort

To address this, we had a backlog of our own ideas for documentation improvements. They could be content ideas, portal ideas, anything was okay. However, many of those tasks were pretty big. And everyone will think twice if they want to take on a complex task when they don’t know what the next development sprint or epic will bring.

#4: Foggy Workload

From the organizational point of view, all Technical Writers are part of a dev team or more dev teams. When you’re in the easy-peasy sprints, you might want to help your fellow Technical Writers. But what are they working on? Every team usually has its own agile backlog and board, with mainly dev tasks and some documentation tasks.

To help someone, you need to ask around, which is a dealbreaker to many people. Or, you need to check multiple boards, which is a dealbreaker for the rest. Most likely, you’ll just have a peaceful afternoon instead.

It works the same vice versa. You don’t know what to do first, but who can help you?

If you have a manager or coordinator of Technical Writers, they don’t really see what you’re doing either. Coordinating such a crowd is pretty time-consuming. Instead of thinking ahead, so creating and following a vision, they spend most of their time with an operational whirlwind.

We tried to solve this by the mentioned backlog and syncing. Still, the syncing was typically interesting for me, the team manager, to know what everybody’s doing. I’d say that this is something that we haven’t really overcome and solved.

#5: Deprioritized Documentation Issues

Following the foggy workload further, you’ll come to a realization. The priorities that Product Owners or Product Managers set may work for the product, but they often don’t work for documentation.

For example, we had a couple of issues regarding best practices that we were aware of. From the product point of view, there wasn’t anything new to implement. But we haven’t been able to address those issues in the docs as we had our plates full of what Devs were implementing.

Development Priorities ≠ Documentation Priorities

Of course, it’s a matter of prioritization and discussion, but the process is by default flawed in this. We again leveraged our documentation backlog prioritized by the documentation team itself. This partially solved the problem. Yet, due to the foggy workload, some problems persisted for a long time.

Next Time: 5 More Sucky Things

Now, you must be thinking that I hate agile and writing documentation within agile development. Well, it’s quite the opposite. I still find this way of working better than others I’ve come across so far. It has plenty of advantages — I may cover those sometime in the future.

Take this list as aspects to pay attention to if you’re transitioning to agile development or already working in one. Next time, I’ll continue with this list of things that are not that great, focused on team building and the place of the docs in the company. Read the next part now…

Do you work in agile development? Have you overcome these problems? What are the issues that you experience in agile development documentation?