Together or Apart: Collaboration Models for Technical Writing

by Tom Johnson on Feb 22, 2010
categories: technical-writing

Today I spent a rather lonely day writing documentation. I had one team meeting, during which our team gathered for what seemed like a brief second. We then departed back to our respective portfolios, most of us working alone and in solitude toward some distant documentation goal.

Some writing teams sit together. They chum with each other all day long about commas and online help layouts. At my first job as a technical writer, I sat in a long row of cubicles we figuratively called "The Technical Publications Office." All day long I could listen to my colleagues say things like "Oh my goodness, this guy is writing fused sentences." Or "Don't you just love it when all your images disappear from Microsoft Word!" or "Hey Tom, can you help me with something?"

You know what I'm talking about — the camaraderie of being in a group of writers, exchanging comments about projects, bantering about this or that. It's a cozy, comfortable feeling, being surrounded by other literary kind.

Agile Environments

It's not like that in my current agile environment, though. In many agile environments, you have to forge your own way, often sitting away from your writer colleagues, embedded among QA, developers, interaction designers, and managers on a project team. Although I'm on a team of eight writers, most of us are spread out in different departments, assigned to different projects. As a result, writing documentation can often be a lonely, long experience alleviated only through Pandora, Twitter, IM, the incoming comments on my blog, and my wife's scandalous posts.

I know it would be a lot more fun to be desk-to-desk with all the other writers in the organization. We could stop every now and then to feign horror at grammar atrocities or mock the edits our SMEs make. We could easily review each others' work, provide feedback about parallelism with topic titles, compare TOC layouts, or discuss the style guide.

But I'm more effective sitting next to other employees working on the same project. Sometimes I wear a QA hat and point out bugs (and explain/show them to developers). Other times I coordinate with project managers about customer feedback and concerns. Other times I ask developers to explain how something works or why they built a function a certain way. You need to be close to your project team to interact with them, right? Proximity has an impact on communication, no doubt. But I'm not so sure ours is the best model to follow.

The Book Sprint Model

Last month leaving an STC meeting, as I was walked through an windy parking lot to my car, I caught up with a colleague, Joe, who works as the sole technical writer at a nearby company.

We talked a little about the meeting. And then he said, "Sometimes I have so many questions. I mean, do you ever think we have the whole model wrong?"

"Huh?" I said. "What are you talking about?"

"You have eight writers in your team. Why don't you all just sit down and tackle a project together and knock out the documentation in a week?"

I'd heard of this model applied to book sprints with open source projects. Anne Gentle has written extensively about book sprints. Tomas at BookSprint Central explains that coming across the idea of the book sprint was the "most important epiphany of [his] professional career." He explains how few people rarely have the time to sit down and write an entire book themselves. It simply never gets done. He says,

I also knew that there was no way i was going to be able to spend all my evenings for a year writing such a book even if i wanted to. Which i didn't. And i had a feeling that while i'd collected a network of incredibly smart people, with boundless experience in this field, everyone else felt mostly the same as me when it came to evenings and years. But I also knew that i could convince almost anyone of these incredibly smart people to give away a week of their time to such as good cause. So there were the constraints. Have: One week of time each from a bunch of smart people. Need: Finished book.

His solution was the book sprint. And it worked. He flew in a group of smart, knowledgeable people and sat them down in a room for a week to write. They produced a completed book, which was downloaded thousands of times and translated into numerous languages.

I like the book sprint idea, quite a bit. It reminds me of the Amish barn raising, or a group of guys pulling together to help someone move.

In fact, as far back as 2005 at a conference in Raleigh, I remember Rick Sapir arguing against the one-writer-for-the-entire-project model that's so common in documentation. Why not have several writers work on various parts of documentation? he said. Everyone takes a little chunk of the application and writes documentation for it. The idea that one writer creates all the documentation for a project is an old model, he explained.

At the time, I disagreed. I said it wouldn't work because you can't write effectively about one aspect of an application without understanding the whole. And to understand the whole takes months of exploration and learning. Not to mention the dozens of project meetings. If everyone has to devote the same amount of time learning the application to write about one small part, isn't that inefficient?

I'm also wasn't sure how help can be put together in such an independent way. Although each topic in a help system is usually a semi-independent chunk, how do you know that the topics Writer A contributes don't overlap, contradict, interfere, or otherwise jar with the topics that Writer B contributes?

On the other hand, the group collaboration model has its benefits. Multiple writers working together can see an application from various points of view. The writers are less inclined to become myopic and routine. They can more freely bounce ideas off each other, make more informed decisions about content and layout, and generally approach the application with twice the brain power.

Book Sprints with Community Projects

One day I'd like to try the book sprint model in a corporate setting. However, since major changes within a large organization are hard to implement, it might be more practical to do a book sprint with our community development projects. We have more than a dozen community-driven projects (most of them small) in which the community participates in the requirements, development, and design. This is one of the cool and interesting aspects of working for a nonprofit organization. Some members want to volunteer their time and talents to further the work. We've been trying to figure out a way to harness their talents.

Previously, I had been pitching the incentive to contribute tech docs as an opportunity to get experience for your portfolio. But that route wasn't so effective. Participation was slow and inconsistent.

Next time, I might contact 10 or so community colleagues interested in helping out and invite them to participate in a book sprint. It could be an entire day, one that we dedicate to documenting just one project. An entire Saturday, or something. I doubt I would fly people out to Utah and put them up in a hotel room for a week, because most people can't take a vacation from their regular jobs for this, but I can see people dedicating a Friday or Saturday or even Sunday to remotely contribute toward a project they believe in, especially if the idea is packaged in the conceit of a "church book sprint."

Whether you're integrated into an agile project team and away from other writers, or together with multiple writers on the same project, increasing collaboration is key.  Rick was right: the single writer working tirelessly in solitude on a manual that he or she authors from start to finish is dead.