I realized that since I keep encouraging writing groups to collaborate with other teams, I should provide some advice. It’s one thing to say “Go do this!” But that does require work, and the least I can do is give you advice that’s helped me.
So here’s one: Don’t present your would-be collaborators with a blank page. If you’re a writer, or if you’ve written anything, ever, you know how daunting a blank page can be. For someone who doesn’t write that often, it’s even worse.
Give them some help
So, how can you help someone get past that blank page? I’ve found that no matter how willing that person is to help you, they can’t start until they know what your expectations are. What information do you need? Telling someone, “Write down everything about this topic” isn’t helpful. In fact, it probably makes things worse: They have to figure out what “everything” means to you. Do you want to know how a feature was coded, what variables they used, why they coded the product using C instead of Java? Probably not. But for some people, that’s a vital part of “everything.”
Limit the scope with templates
As far as the “what” goes, I use templates to help someone get started. In addition to being more specific when telling your collaborators what you want from them, presenting a template helps them focus. Plus, they’re no longer staring at a blank page: Instead, they can look at the sections that you’ve created and they’re thinking about what they can provide for each. And if they’re really good, they’re thinking beyond the template, about things that you might not have considered.
So it’s up to you to give them a template with headings, and example text, that clearly tells the prospective writer what you’re looking for.
For example, if you wanted someone to document a task:
Description of the task
Write a high-level, 1-3 sentence description that explains this task and why someone would do this.
What does the user need to do before they can perform this task?
Would a user perform this task before, after, or with another task? List those other tasks here.
Briefly, what are the steps required for this task? Assume that they’re using the product and have completed the requirements.
Finishing the task
How does the user know that the task is completed successfully?
Errors and Troubleshooting
What happens if the task completes unsuccessfully?
What happens if the user does something wrong: What do we tell them, and how can they fix it?
This is a very simple example, and many people are used to these if they have to write product requirement documents, technical specifications, or other business docs that fall into the product management area.
But…”many” is not all (and might not even be all that many), and I’ve never found that a template hurts the process.
Setting expectations about style
This is the more difficult area. When I started rounding up people to help with the documentation, I heard a lot of variations of this statement: “I’m not very good at writing.”
So I tried to encourage them by telling them that it didn’t matter, that I’m really interested in the raw information, and that I can do whatever editing is required. My job is to worry about structure and word choice, but I can’t do that without the information that’s in their heads.
I’m not entirely sure how well this worked. I think it helps, but collaborators still worry that what they write won’t be good enough, and they worry that I’m going to publish the information exactly as they hand it to me.
I’ve tried writing short style guides and asking collaborators to read and follow those, but now I believe that only adds another barrier to entry. Suggest that they try to follow the corporate voice (assuming your company has settled on one), or something similar to the existing documentation. But that runs the risk of forcing collaborators into a style that’s more formal than they’re used to, or more casual than their normal style (although I can’t say I’ve had that particular problem).
Breaking down those barriers
Break down those barriers by giving your prospective collaborators concise, informative templates. If possible, allow them to write in their own style, and stick to editing only what you need to. Add informative headings and comments to the templates, to banish the terror of that blank page and help your collaborators focus on writing the content that your audience needs, instead of making the collaborators guess what might be important to your customers.
And encourage those collaborators to think beyond those templates, to help you expand your documentation with more of that great information that’s been locked inside their heads.