Asking The Hard Questions - Practices

You should start thinking about the user manual right at the start, andtry to have the following questions answered by the time you actuallyget down to writing it.

1. Who is the audience?

This helps you decide the tone and level of technicality of yourlanguage, the depth in which the concepts need to be explained, and(very important) the analogies that you can use (familiar ground is bestwhen trying to explain something new). Knowing the following parametersabout the intended users would help:

• What is their average age?
• Which computer software packages are they familiar with?
• What are the obstacles they usually experience while using thesesoftware applications?
• What are the top five task(s) they plan to use your software for?
• What is their current level of expertise (novice/intermediate/expert)in using particular software packages?

This information is useful when your software builds on existingsoftware currently in use. For example, if you are delivering anintranet email utility that plugs in to Microsoft Outlook, it would makesense to find out if your audience has ever used it, and to what level.

This also brings up an important decision: do you decide the minimumtechnical expertise required of the users of your software, state it assuch in the user manual, and get on with things? Or, given the resultsof your user profiling, do you take on the responsibility of bridgingthe gap between the current and required level of expertise (maybe byproviding a short tutorial as a precursor to the manual)? The scheduleand budget would normally make this decision for you.

The ideal scenario, of course, would be that you get all thisinformation by interviewing the actual users. In case that isn'tpossible, your marketing and QA departments should have the requisiteinsight into the target audience.

Besides this, some research into the business processes of the targetorganization will give you even greater insight into the context of usertasks, as well as fodder for analogies that may be easily understood ythem. Additionally, customer meetings, including technical reviews, aregreat sources of audience information.

2. What is the scope of the document?

While the broad goals of the user manual would be to provide informationon the installation, usage, administration and troubleshooting of theproduct, questions like these would help scope the document further:

• Current user expertise versus required expertise: What is the extentof background/explanation that needs to be given?
• Supported platforms: What are the different platforms/operatingsystems that the manual should address?
• Troubleshooting: What level of troubleshooting are the users supposedto handle? Is there a reporting mechanism for support? Is there separatedocumentation for troubleshooting?

3. What tool should you use for document development?

The user manual, online help and searchable help essentially build onthe same information. Which means that your choice of tool, and itsability to allow you to reuse information from one document for thefaster development of another, is crucial (especially if your project'son a tight schedule).

A number of good tools are available for this purpose. I like RoboHelp(http://www.ehelp.com/), though if you're working with XML, you shouldalso look at the XMLMind XML Editor (http://www.xmlmind.com/)

4. What is the mode of document delivery?

The user manual can have two modes of delivery and distribution:

• Print: In this case, you take the responsibility of printing itin-house and delivering it to the customer (many customers demand this).Thedownside: you get to incur printing and distribution costs (and theaccompanying logistical issues), together with recurring costs everytime the documentation is revised.
• Electronic: In this case, you may choose to deliver documentation inelectronic format, via CD-ROM at installation time, or providedownloadable material on your Web site. The de facto standard for suchelectronic documents is Adobe's Portable Document Format (PDF).

Again, if you're not sure what the final format will be, and if you'recomfortable with XML, it's worthwhile considering developing yourdocument in XML; this may then be easily converted into any other formatat a subsequent stage.

>>> More Practices Articles          >>> More By Deepa L, (c) Melonfire

blog comments powered by Disqus