Who Should Write Your Software Documentation? Not Tech Pubs
Many businesses have a Technical Publications department that is in charge of writing software documentation. Most customers never read software documentation. Those two facts are directly related.
Technical Publication Departments Are Ill Equipped to Create Software Documentation
Tech Pubs have almost no interaction with actual users. They create “requirement” documents from the various stakeholders (marketing, compliance, engineering, sales, service, support, etc.) and then create documents that meet those requirements.
Unfortunately they rarely ask users what they need.
This lack of direct connection with end users means that tech pubs has no idea what information is actually important to their users. They don’t know what questions the users have. They don’t know how best to answer those questions. The end result is software documentation that meets the requirements of “stakeholders” but not users.
Guess what? The stakeholders aren’t going to use the documentation.
Your Customer Help Desk Has the Questions and the Answers
The people who are best equipped to write your software documentation are those that are working the customer help desk. They may not have training in technical writing but they know exactly what the most important issues are for your users. They know what questions need to be answered. They know the real answers to those questions.
Have your help desk people write your software documentation. Their daily interaction with users will help them write documentation that is much more useful.
Create Documentation That Actually Helps Your Users
Download our free webinar: Why Your Documentation Stinks and How to Fix It
May 26th, 2010 at 5:29 pm
Hi! I one of those customer service/help desk kind of people tasked with producing client documentation for an 8-year-old system that’s never been documented. I LOVE your format for your own PDF User guide. Any chance that you could publish the template file so that beginners like me can hit the deck running? It just looks so clean! Thanks!
May 26th, 2010 at 6:03 pm
Claire-
Are you using ScreenSteps? We are just using the standard ScreenSteps PDF template with our logo added to the top. If you are trying to get started creating your manual I would suggest reading this article:
5 Steps to Improving Your Software Documentation
Or did I misunderstand your question?
May 27th, 2010 at 1:39 pm
Thanks! Newbie mistake. I’m the proud new owner of ScreenSteps Pro, and have only exported to Word. I didn’t see the PDF template. BTW, thanks for all the extra information on the “process” of documentation. It goes far and above just the use of your software, and it helps alot.
May 31st, 2010 at 9:34 am
Claire- Glad to hear you are finding the information useful. Once you get the process down, writing useful documentation becomes easy.
June 12th, 2010 at 2:40 am
[...] http://www.bluemangolearning.com/blog/2010/05/who-should-write-your-software-documentation-not-tech-... [...]
June 12th, 2010 at 1:34 pm
[...] in touch with the software user. Greg DeVore of ScreenSteps pointed me to a post he wrote about getting the people who work the customer help desk to write the documenation. His post includes a section provocatively headed "Technical Publication Departments Are Ill [...]
June 17th, 2010 at 10:15 am
[...] Just read a good post by Tristan Bishop titled “What if no one READS the manual?” Click through to read all the details but the gist is that technical writers need to become more engaged with end users. This is exactly along the lines of what we said in our post about who should write your software documentation. [...]
June 30th, 2010 at 10:55 am
I navigated here from the ISTC newsletter. The company I work for doesn’t have a Tech Pubs team and has no intention of creating one, so as the sole tech author (part) of my job is to come up with ways of helping other people in the business create documentation, including help. Getting Help Desk staff involved is a very good idea, and one I will look into further.
However, I have to take issue with the sweeping generalisations about tech authors having little or no interaction with the help text audience, or that their experience is usually limited to writing requirements documents and little else.
One of the first things I learned when I became a tech author in 1998 was the importance of writing for the audience, whether that’s an end user or a colleague. A skilled tech author can translate for different audiences, whether they’re internal teams or stakeholders, third parties, or customers. Furthermore, we aren’t all isolated from our audiences. There are an increasing number of ways to engage with external readers, and not all help documentation is written for people outside the environment it is generated in.
I fully accept that some tech authors or Tech Pubs departments would probably benefit from more engagement with their audience, but I can’t believe the only solution is to hand over a key skill/role to another job title.
An interesting article that’s definitely got my neurons firing. Thank you, and I’ll be back to read more.
June 30th, 2010 at 11:17 am
John- Glad you liked the article. I’m not saying that tech writers lack the skill to write for their audience. I am saying that they are too far removed from the front lines. Who feels the pain when the documentation is incomplete? Tech support. Who feels the pain when the documentation is wrong? Tech support. Who has the biggest interest in the documentation answering questions clearly an quickly. Tech support.
Since they feel the pain they have the most incentive to get it right. Also, since they are on the “front lines” they have the quickest and most accurate knowledge as to what is really needed.
You can establish a process where tech support suggests a topic to be documented, then the tech writer authors it, and it gets approved and then gets published a week or a month later. Or you can just let the tech support person add to the documentation.
Maybe it’s not that tech support needs to take over the tech writer’s job but instead that tech writers need to be doing the job of tech support.