6

At work we provide three types of technical document, aimed at different kinds of users :

  • The Quick Start Guide. Single laminated sheet, illustrations and basic explanation.
  • The handbook. A5 format book, lots of pictures, limited descriptions.
  • The manual. A4 format book, illustrations (drawings, photographs), detailled descriptions.

Are we missing a trick with a combined document, or is there a level of detail we're missing? The thing in question is a measuring instrument, and our customers range from casual distributors who just want to show their customers through the menu structure and will never measure anything themselves to university research departments who want to consider the effect of our equipment on the process being measured.

The answer "No, you've got it about right" would also be valuable.

  • 5
    No, you've got it about right. I wish more people were doing this. An useful approach to the handbook though, is instead of descriptions to give procedures: To achieve result X (e.g. perform a measurement; calibrate the device, replace batteries, set up a permanent test stand etc) follow these steps: 1., 2., 3. I'm less interested what given button does and what given LED shows, I'm interested how to get my work done: which buttons to press, and which LEDs to observe. – SF. Sep 22 '17 at 10:50
  • Thanks for the quick response, and a very good point - I'm still consciously trying to change "this is what this thing does" to "this is how this thing can do what you want it to do". – ItWasLikeThatWhenIGotHere Sep 22 '17 at 11:16
  • 1
    How many pages are the handbook and the manual? I have seen the two combined effectively with cross-referencing. – S. Mitchell Sep 22 '17 at 14:04
  • 1
    Around 25 for the handbook, 50 for the manual. There is a "Refer to manual" symbol (I'm tempted to say it says "RTFM", but it's a representation of a book) in the handbook, and a little telephone symbol (defined as "contact Customer Support) in the manual, so there's a kind of cross referencing going on already, but let me know if you had something different in mind. – ItWasLikeThatWhenIGotHere Sep 22 '17 at 17:42
  • 1
    Is this primarily print or online documentation? If print, I'm done. If online, then you can merge levels with links from overview to detail levels. This would also be an opportunity to link from (the great) how do I do this approach to more on what each widget does details so the user can also figure out how to do his/her task if it is different from the ones you detail. – Joe Sep 27 '17 at 0:19
7

There is no real way to tell if you are doing enough, of doing the right things, just from a brief description of your product and your users. The questions you really have to come to grips with are:

  • When your user look for information on how to do something with your product, are they finding it?

  • When people have a problem using your product, where do they look for information. For instance, if most of them a Googling when they have a question, is it coming up in searches and do they recognize the results they get as the results they want?

  • Are people calling tech support to ask questions that are answered in the manual? If so, then either they didn't read the manual or they could not find the manual, or they could not find the information in the manual. (Maybe they Googled first and did not find anything.)

  • Does your documentation cover the task your uses are actually trying to perform? Most user tasks are founded in real-world business problems and merely use the feature of the product as part of completing the task. But many manual just describe how to use product features without showing how they relate to business tasks. Are your users struggling to connect your product's features to their business problems?

  • Does your documentation address users at their level? Does it make the right assumptions about how they are trained, the experiences they have had, and the tasks they are trying to perform. Does it speak to them in terms that are familiar to them?

Finally, you have to decide what you are trying to accomplish with your documentation:

  • Are your just trying to meet regulatory requirements? Sometimes a company owns a market niche and does not have to differentiate themselves through ease of use or advertise themselves through high quality content. In this case the only people you have to satisfy are the lawyers.

  • Are you trying to make sure your core customers are successful and reduce the adoption costs of your product for them? In this case you need to make sure you are covering the core tasks at the right level so that users can get up to speed quickly.

  • Are you trying to establish thought leadership and increase your visibility in a competitive market by emphasizing ease of use? In that case you need to produce really high quality documentation that goes beyond core functions and help people address their business problems. Documentation can be a huge source of lead generation for your company if you are addressing business problems that people are search for solutions to on the Web. It can also bolster the reputation as a company that really understands the business space, which can increase potential customers confidence in your product.

Many business, of course, just do whatever they see other similar businesses doing, or what they conceive the conventions of their industry to be. But the way people access information, the level of communication they expect from vendors, and the way the shop for technology have all changed radically and the old conventions don't apply today. This opens up a huge potential for companies that get content right for the new world, and huge peril for those whose competitors get it right before them.

| improve this answer | |
  • Thanks Mark - nice to have caught the attention and considered response of a 5-figure rep. on my first posted question. Congratulations on the Moderator position. – ItWasLikeThatWhenIGotHere Sep 22 '17 at 17:51
  • Just spotted the Moderator announcement was six years ago. Ah well. Still holds. – ItWasLikeThatWhenIGotHere Sep 22 '17 at 18:02
  • 2
    It gets updated whenever the mods change. I've been a mod for less than a week. So, congratulations accepted. Thanks. – user16226 Sep 22 '17 at 18:14

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.