Writing 200 Page Manuals That No One Will Read is Insane
This morning I read a post by Tom Johnson titled “If No One Reads the Manual, That’s Okay”. In it the author describes how he is writing a 200 page manual that no one will ever read and that somehow that is all right.
That no one will read a 200 page manual is perfectly OK. That people are still writing them is insane.
In the comments of the post, some technical writers were making the case that users needed to read the manual. But it doesn’t matter what you think users should do, only what they will do. The real problem here is that technical writers keep doing the same thing and expecting different results (the definition of insanity).
Here’s a suggestion, instead of talking about how people should use the content you create start trying to figure out why they aren’t using it.
And then fix it.
Don’t accept things the way they are.
Make your content useful and make it accessible when and where the user needs it.
Here are some questions to ask yourself (these all relate specifically to software manuals):
What happens when a user doesn’t read the manual? One of the things they do is contact support. Develop and deliver your documentation in a way that can be used in a support situation.
What are your users asking? Are they asking “Could I please have an overview of the Upload tab?” or “How do I upload a file?” Is your documentation structured around the questions your users have or the way your application is organized? Which would your user prefer? Which would be most useful to your users and your organization?
Where do users ask questions? They call, email, post to message boards and use Twitter. Can you deliver the content your users need (your manual) in the places where they are asking the questions?
These are the questions technical writers need to be asking themselves if they want to move beyond just fulfilling requirements to really adding value to their organizations.
Several months ago we recorded a webinar on this exact subject called Why Your Documentation Stinks and How to Fix It. Check it out if you want some new ideas on how to get people to read the documentation you write.
December 29th, 2009 at 2:45 pm
Thanks for the link. I agree with your suggestions on how to address situations where users are using the help — especially integrating with support documentation.
Just so you don’t think I’m insane, in my post I said that users aren’t using any form of help because they’re already familiar with the application. The manual is for business continuity, mainly. In that situation, what purpose does a manual serve? And how will exploring alternative help formats fix the situation?
I appreciated reading your post and will check out your webinar.
December 29th, 2009 at 3:28 pm
@Tom – I’m working off of a bunch of assumptions here, but it sounds like the whole point of the project is to have some sort of “insurance” in case your organization had to replace people on the team. If that is correct, then the target audience is a new member, just joining the team.
Look at two possible scenarios:
The new team member comes aboard and an existing team member needs to train the new guy. Having the manual broken up into small segments the trainer could point the newbie to would be very helpful. That way he/she can customize what parts of the documentation the newbie is receiving without any hassle. Some sort of online format that breaks the manual up into separate pages would be ideal since the trainer could just send a list of pertinent urls.
The whole team needs to be replaced. There is no one there to train the newbie (very unlikely, but possible). The newbie really needs to know what tasks they need to perform and how to do them. Some sort of online resource, such as a wiki would be ideal because if the information is out of date, it is useless. The team can list the tasks they perform each day, each week and each month. Each list item points to a page with a “how-to” of how to perform that task. Once every couple of months ask them to look at the list and see if it is still accurate. Since the point is “insurance” you need some way of making sure the content stays accurate or it really does become worthless. A 200 page PDF won’t get opened and since no one will look at it, no one will know if it is out of date.
If it really is likely that no one will ever need this thing then I still think it is crazy to create it. Too much wasted time. I would just sit down with the team, turn on some screen recording software, ask them what they do each day, and then ask them to do it. In about an hour or two you should have enough information to be useful if disaster were to strike. And on top of it, you guarantee that all of the information will be accurate because you recorded them actually performing the tasks.
Like I said, these are a bunch of assumptions on my part, so they may or may not apply to your situation.
December 29th, 2009 at 5:47 pm
Trevor, I prefer 400 page manuals. In any organization (and private home) the safest place to hide money, passwords and other well kept secrets is an Excel Manual of the size of 400+ pages. Were am I going to tuck my secret stuff away :) Unfortunately they too gave up on these manuals. regards Bernd
December 29th, 2009 at 6:30 pm
Thanks for your response, Trevor. By the way, I like how you make your comments highlighted. I’ve been trying to figure out exactly how to do that. Did you customize the comments in your theme or was it included in the theme already?
Re breaking up the manual into chunks, I forgot to mention that it’s both an online help and manual. I usually just single source between the two.
You’re definitely right about the need for a wiki to keep things up to date. I do want to convert all my docs to a wiki format. I may just do that this coming year, because I so rarely work with this project and department, I can’t imagine that the content meets all their needs.
The only drawback with wikis is that they’re harder to print.
December 30th, 2009 at 10:03 am
Just wanted to point out that Greg wrote this post, not me.
December 30th, 2009 at 11:29 am
@Tom – As far as highlighting the comments – that is easy. Each comment in WordPress has various classes applied to it by default. If the comment is by the post author then it will have a class of “bypostauthor”. I checked your blog and the same class is on your comments there. So just add some css for
ol.commentlist li.bypostauthorand you can separate out your own comments from others on the blog.Wikis not printing is a major drawback, but not being able to print is an inconvenience, content that is out of date is worthless (or at least mostly worthless). That is actually one of the reasons we created our own system. It is like a wiki in that any authorized user can edit the content, but it is coupled with a desktop authoring system which means we can also export the individual modules, or complete manuals out as PDF, Word, XML or whatever else we need.
I’m a big believer that up to date and accurate content trump all other considerations. As soon as a user reads inaccurate or out of date content they no longer trust the system and will no longer go to the documentation as a resource.
December 31st, 2009 at 3:46 pm
Thanks Greg! That seems so simple and it works. I can’t believe I didn’t do it earlier. Thanks for letting me know that exact style. I’ve been wanting to implement this highlighting like they do on Techcrunch for a while.