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

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 second part, I’ll focus on Technical Writers’ team-building and place in the company.

Where Were We?

I work at Kentico, a software (CMS) vendor, as a Customer Education Leader (a manager of documentation and training for customers). We’ve been writing documentation in agile development for many years. As with any other way of working, this setup has its pros and cons.

#6: Time Wasted on Useless Meetings

One of my former colleagues, when she got to Kentico, called it “meetingitis.” It’s when Technical Writers spend a lot of their time on meetings. Groomings, plannings, retrospectives, reviews, dailies. And those are just Scrum meetings. Let’s throw in documentation syncs and an ad hoc meeting about this or that technology.

Technical Writers just sit at dev team meetings for 90% of the time.

Technical Writers are part of the dev team. Still, even though there could be information interesting for them, most meetings are not. Bringing a laptop means that you’re not at the meeting anyway, only working from an environment worse for focus. This decreases what Technical Writers can deliver overall.

#7: Being Taken for Granted

As Technical Writers don’t think about code unless they have to, Devs don’t think about documentation unless they have to. Praise those that actually do think about the docs.

#8: Core Part of the Team… But Not Really

There are three ways to hold grooming. One, you estimate technical writing effort within development effort. That misleads prioritization and planning, though. A team won’t take something to a sprint because it’s too large even though they’d manage to do it — it’s just not visible from one number. In our case, this system showed as inadequate and was dropped entirely throughout the years.

Three ways to groom issues and plan sprints. But no good one.

Two, you estimate development effort only, not counting the Technical Writer’s job. This misleads prioritization and planning from the exact opposite point of view. A team will take something to a sprint because they don’t see that their Technical Writer has their hands full already. And don’t forget that you exclude a core part of the team, so it’s a bit unsystematic. In this case, Technical Writers must participate during the planning and be able to veto the sprint if it’s too much.

#9: Less Contact with Other Technical Writers

Dunbar’s number is a number of people “with whom one can maintain stable social relationships.” At work, you have several people that you know well. The chances are that if you work in IT, you’re introverted, and the number is smaller. So, the more you deep-dive into dev teams, and Developers become the ones in your social circle, the less you know fellow Technical Writers.

#10: You Limit Yourself to a By-Product

Number 10 in the list connects all previous points and describes the most important. When you create documentation in agile development, you create a by-product for your main product. Something of less importance. Something that doesn’t deserve its own way of working. A necessary evil.

  • “Don’t spend that much time on internal documentation.”

Break That Vicious Cycle

All the mentioned sucky things have one thing in common. You can always work against them and minimize them. But even if you minimize something negative, it’s not going to be positive, just a little less negative than before.

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

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