Truly Agile Documentation: Separate Docs From Development

The holy grail of documentation teams is often to switch from the waterfall approach to the agile way. The beautiful land of development teams working in Scrum teams, in which their Technical Writer works on the sprint tasks. It indeed is agile development, but is it agile documentation? In this part, I’ll focus on why the key is to free documentation from development.

How I Met Agile

I started working at Kentico, a software (CMS) vendor, seven years ago. It was not that long after they switched the waterfall approach for agile. Scrum was the chosen agile framework. There were a couple of teams of around ten people, where all the typical agile roles were represented.

If I should grade how well we worked under agile development, I’d give it B. Maybe even A–.

As far as I know, Kentico has always had a relatively lot of Technical Writers compared to other companies. When I started, we used to have five Technical Writers and a team coordinator for eight development teams. That’s because we didn’t just write the docs. We also wrote code examples ourselves, maintained our docs system, helped Product Owners with user stories, and so on.

In most cases, we managed to finish sprints on time. Yes, our documentation level and style weren’t the same as we didn’t communicate among Technical Writers that much. But even that, we improved over time.

Improving Something That Works? Are You Crazy?

Even though we worked well within agile development and did what was expected of us, our documentation could have improved. The problem was that we saw just within the scope of the development team or teams we were working for. Sitting with them, collaborating with them, snacking with them too. It’s natural to take over the internal devs’ point of view in such an environment.

How would I grade how well we covered documentation priorities? Hmm, C?

Although subtle initially, they became burdens we needed to get rid of. They won’t prevent you from creating docs, but they’ll slow you down and prevent you from creating something more.

I counted ten things that worked poorly for us in agile development. You can read about them in my previous articles:

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

Wasn’t It Just Agile Done Poorly?

We definitely did some things wrong, and, for sure, there were mistakes on our way. Also, agile isn’t just Scrum. Working in Kanban, some of the issues could be solved more easily. But these problems don’t show right at the beginning. For new products, they are typically so small that you don’t even notice them. They slowly expand the longer you’re working on a product. Until they are already daily bread, and they start bugging you.

Agile development isn’t against documentation, but it isn’t in favor of education either.

As a Documentation Manager, I was going over what we can do better many times. More syncs? Daily stand-ups for Technical Writers? A backlog for extra tasks? Most improvements of the current process were successful, but none of them brought the revolution I was hoping for. Especially the tenth problem mentioned in the linked articles above — documentation being just a by-product — is very hard to overcome. Eventually, it was clear that most of the constraints are brought by the agile development process.

So, Waterfall Is Better Than Agile, Right?

Before I continue, let’s stop for a minute. I’ve spat fire towards agile not just here but also in the linked articles. But that doesn’t mean that I don’t like agile. For product development, agile provides an ability to respond to changes more quickly. Although it may seem that it creates a mess for the documentation world, it just requires Technical Writers to adapt to the changes as well. And that’s a good thing.

As Technical Writers, we are here to educate our users, to help our company fulfill its mission. We are here to write what should be written. As Technical Writers, we must push back against writing long essays to write every little edge case or writing articles on bugs that are in the product by design. We are not here to write what can be written. Agile focuses you on that much more than waterfall.

If you’re in the waterfall phase, go for agile with everything you’ve got, it’s a step forward.

While agile may cause that you’ll occasionally rewrite something you wrote before, it’s a low price for what it has to offer. As this isn’t an article on transitioning to agile, just a couple of points:

• You’ll get to document something live, you’ll be part of the development process.
• Devs will still remember what they coded when you ask them. They work on it at the same time as you do.
• You’ll get to do more versatile activities. You’ll start contributing to microcopy, create your own tools, and much more. Look at the stuff I wrote at the beginning about what we’ve all been doing.
• Your workload will be, in general, more even.
• You’ll be able to split your team across products, getting to know the product deeper.

As product development benefits from smaller modules that are incrementally extended, documentation benefits too from creating smaller tutorials and references. They are oriented towards use cases and scenarios, instead of articles that are maybe complete but never read.

So, the answer isn’t going back to being stoic. The answer is to be even more agile.

Viva la Revolución!

And that there can’t be a revolution until we separate documentation and development. Luckily, in our case, it was when the Development department itself was thinking about tweaking its development process. They wanted smaller, more agile teams, consisting of Devs only.

And that’s when it happened. We created a Customer Education team where all Technical Writers (we call them Content Developers) work together as a team, sit together, and treat development and all the other tasks the same way.

Shift the Role in the Company

From individuals working in development teams, just syncing among each other, we’ve changed. We’re now running our own agile team, using a modified Scrum. As a Documentation Manager (we call my position a Customer Education Leader), I’m sort of a Product Manager and Scrum Master in one person. Still, I’m trying to decentralize and rotate many duties to the team to be self-sufficient.

Not only have we separated from development teams, but we’ve also separated from Development as a department. We are now positioned in Customer Success. This nudges us closer to the customer and further from the internal perspective.

As we still need to fulfill our “supporting responsibility” for Development (and other departments) by publishing about new features, we use one-week sprints instead of the typical two weeks. That gives us the ability to adjust priorities pretty quickly. We originally started using the two-week sprints, but it became cumbersome as ad hoc requests appear, and they usually come with a hot deadline.

One-week sprints allow you to be agile even for your agile development.

Even though it has definitely worsened the relationship between Devs and Technical Writers, they haven’t broken. To this day, the relationship is still on an outstanding level with Technical Writers Devs knew personally. Newer Technical Writers that got on board after we did the switch don’t reach the same level, but their relationships are still decent.

The Time Gained

After we switched, we started thinking about what we can do to support the company with a product that we create. Because documentation is a product too.

Since we separated from development teams around two years ago, we managed to ship out everything to product rebranding and redesign in time, oversee the building of our own documentation system, our brand new e-learning — incl. content, portal, and video creation — and build a close team, where everyone can rely on each other.

With every project, our limits move forward, and we get better. I can’t imagine that we’d create the whole e-learning portfolio with a functional portal if we still were part of the development teams.

Technical Writer’s job is diverse, and it’s one of the reasons why I enjoyed being a Technical Writer. But with the new time that we gained, the diversity, learning, and possibilities multiplied. Even for me, as the team’s manager, it’s not just about coordination and people management. I can push for projects that will help our customers, our company, and in the end, us individually as well.

This Doesn’t End Here

I don’t know why but I always pick a too large topic to discuss within one reasonably long article. Even though a lot of Technical Writers, including my colleagues, have an attention span of African Cichlids (that is, apparently, a very long one), I’m going to continue with our workflow and way of working in the next chapter.

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.