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.

This two-part series focuses on the cons. The second part you’re reading right now continues where part one left off. If you haven’t read that one yet, I highly recommend reading it too. You’ll read about problems with workload and priorities. And without further ado, let’s continue…

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

Our first thought was to stop coming to organizational meetings and come to technical discussions only. So Technical Writers stopped coming to retrospectives and dailies. However, retrospectives are essential to maintain the relationship between Devs and the Technical Writer. When you stop coming, you won’t have a chance to adjust how Devs operate and how they “think of you.”

In our case, the culprits were the other meetings, namely groomings and plannings. Even though they seem to carry the most valuable information, groomings are usually too focused on the technical solution, and you can find the results of plannings in your project management tool such as Jira.

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

But the more you’re there for Devs, the less Devs need to think of the docs. One day, it’ll come to this, “You’ll create tasks when you need them, right?” You can do that — you’re coming to all of the meetings, so you have all of the information. Yet, it moves Devs further from the documentation. Over time, they’re going to know less of what’s documented and what the customer’s point of view is.

This doesn’t have to be a problem if your Dev/TW ratio is right (i.e., the number of Devs per one Technical Writer). But it’s a problem because you want Devs to know customers’ scenarios as much as they can.

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

Three, you can estimate Devs’ and Technical Writer’s efforts separately. While certainly the most accurate option, I haven’t seen this in practice. I guess that there would be some pushback, with the main reason being it would slow groomings. But I would argue that throwing in one more number or T-Shirt estimate, given by one person, shouldn’t take much time.

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

What that leads to is a less unified way of writing and a different voice and tone used throughout the docs. When I got to Kentico, we were five Technical Writers with our coordinator, everyone with a unique writing style, and we met once every two weeks.

Building a style guide is the first substantial building block. Meeting more often is also important. Start with syncing what has been done and what should be done. Let the team also discuss on a personal level. Don’t force your teammates to be friends but create an environment where being friends is encouraged.

In any way, though, the time Technical Writers will spend together in agile development is limited. Most likely, they won’t become friends unless they’re a perfect interpersonal fit.

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

The agile manifesto states, “Working software over comprehensive documentation.” I interpret it as two things:

• “Don’t save a buggy product with notes in the docs.”
• “Don’t spend that much time on internal documentation.”

With both, I agree with my whole heart. So what am I talking about? This problem wasn’t brought by agile; it’s a problem way older. The industry standard is that your company solves customer scenarios (i.e., fulfilling its mission statement) with a product, and the product solves product scenarios with documentation.

If you treat documentation as a secretary to your product, you won’t get anything else than help to your existing product. You can’t expect anything above “How to do scenario X with product Y.” And agile development won’t help with this problem at all.

When a typical agile team consists of several developers but only one Technical Writer (or even less as Technical Writers take care of more teams), they’ll never focus on documentation. We couldn’t find a way out of this within agile development, so we came up with a different way of working in one of the two products.

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.

As I wrote in part one, I’m actually quite a fan of writing documentation in agile development. At least in general. The fact that agile development shortens development time and focuses on the most critical things is vital when creating software. In this case, it’s better to spend some time minimizing negative impacts here and there than to continue working with the waterfall model. Documentation might not thrive when being written in agile development, but it’s definitely a step up from any linear approach.

So, no more sucky things in this series. Next time, I’d like to introduce the mentioned way of working, which I call truly agile documentation. We’ve been running for over a year, and it’s been working well so far. Better than documentation in agile development ever did. Stay tuned.

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

Thanks for reading the article. If you’d like to get notified when I publish something new, follow me on Twitter, LinkedIn or add my RSS feed to your reader.