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

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.

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 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.

#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.

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.

#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.

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.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Tomas Nosek

Tomas Nosek

Customer Education team leader, occasional blogger, a movie person, comfortable traveler. Find all my articles at nosek.net.