Practices
  Home arrow Practices arrow Page 3 - Writing A User Manual (part 1)
Dev Shed Forums  
Administration  
AJAX  
Apache  
BrainDump  
DHTML  
Flash  
Java  
JavaScript  
Multimedia  
MySQL  
Oracle  
Perl  
PHP  
Practices  
Python  
Reviews  
Security  
Smartphone Development  
Style-Sheets  
Web Services  
XML  
Zend  
Zope  
Mobile Linux  
App Generation ROI  
IBM® developerWorks  
Forums Sitemap  
E-Commerce Hosting  
Linux Web Hosting  
Managed Hosting  
Small Business Hosting  
VPS Hosting  
Weekly Newsletter

 
Developer Updates  
Free Website Content 
 RSS  Articles
 RSS  Forums
 RSS  All Feeds
Write For Us Get Paid  
Request Media Kit
Contact Us  
Site Map  
Privacy Policy  
Support  
 USERNAME
 
 PASSWORD
 
 
  >>> SIGN UP!  
  Lost Password? 
Google.com  
PRACTICES

Writing A User Manual (part 1)
By: Deepa L, (c) Melonfire
  • Search For More Articles!
  • Disclaimer
  • Author Terms
  • Rating: starstarstarstarstar / 25
    2002-12-27


    Table of Contents:
  • Writing A User Manual (part 1)
  • Step By Step
  • Asking The Hard Questions
  • Making Friends And Influencing People
  • Being Conventional

  • Rate this Article: Poor Best 
      ADD THIS ARTICLE TO:
      error-file:tidyout.log Del.ici.ous error-file:tidyout.log Digg
      error-file:tidyout.log Blink error-file:tidyout.log Simpy
      error-file:tidyout.log Google error-file:tidyout.log Spurl
      error-file:tidyout.log Y! MyWeb error-file:tidyout.log Furl
    Email Me Similar Content When Posted
    Add Developer Shed Article Feed To Your Site
    Email Article To Friend
    Print Version Of Article
    PDF Version Of Article

     
     
    ADVERTISEMENT


    Writing A User Manual (part 1) - Asking The Hard Questions
    ( Page 3 of 5 )

    You should start thinking about the user manual right at the start, and try to have the following questions answered by the time you actually get down to writing it.

    1. Who is the audience?

    This helps you decide the tone and level of technicality of your language, the depth in which the concepts need to be explained, and (very important) the analogies that you can use (familiar ground is best when trying to explain something new). Knowing the following parameters about 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 these software 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 existing software currently in use. For example, if you are delivering an intranet email utility that plugs in to Microsoft Outlook, it would make sense 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 minimum technical expertise required of the users of your software, state it as such in the user manual, and get on with things? Or, given the results of your user profiling, do you take on the responsibility of bridging the gap between the current and required level of expertise (maybe by providing a short tutorial as a precursor to the manual)? The schedule and budget would normally make this decision for you.

    The ideal scenario, of course, would be that you get all this information by interviewing the actual users. In case that isn't possible, your marketing and QA departments should have the requisite insight into the target audience.

    Besides this, some research into the business processes of the target organization will give you even greater insight into the context of user tasks, as well as fodder for analogies that may be easily understood y them. Additionally, customer meetings, including technical reviews, are great sources of audience information.

    2. What is the scope of the document?

    While the broad goals of the user manual would be to provide information on the installation, usage, administration and troubleshooting of the product, questions like these would help scope the document further:
    • Current user expertise versus required expertise: What is the extent of background/explanation that needs to be given?
    • Supported platforms: What are the different platforms/operating systems that the manual should address?
    • Troubleshooting: What level of troubleshooting are the users supposed to handle? Is there a reporting mechanism for support? Is there separate documentation for troubleshooting?
    3. What tool should you use for document development?

    The user manual, online help and searchable help essentially build on the same information. Which means that your choice of tool, and its ability to allow you to reuse information from one document for the faster development of another, is crucial (especially if your project's on 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 should also 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 it in-house and delivering it to the customer (many customers demand this). The downside: you get to incur printing and distribution costs (and the accompanying logistical issues), together with recurring costs every time the documentation is revised.
    • Electronic: In this case, you may choose to deliver documentation in electronic format, via CD-ROM at installation time, or provide downloadable material on your Web site. The de facto standard for such electronic documents is Adobe's Portable Document Format (PDF).
    Again, if you're not sure what the final format will be, and if you're comfortable with XML, it's worthwhile considering developing your document in XML; this may then be easily converted into any other format at a subsequent stage.

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

       

    PRACTICES ARTICLES

    - More Techniques for Finding Things
    - Finding Things
    - Finishing the System`s Outlines
    - The System in So Many Words
    - Basic Data Types and Calculations
    - What`s the Address? Pointers
    - Design with ArgoUML
    - Pragmatic Guidelines: Diagrams That Work
    - Five-Step UML: OOAD for Short Attention Span...
    - Five-Step UML: OOAD for Short Attention Span...
    - Introducing UML: Object-Oriented Analysis an...
    - Class and Object Diagrams
    - Class Relationships
    - Classes
    - Basic Ideas





    © 2003-2009 by Developer Shed. All rights reserved. DS Cluster 1 Hosted by Hostway
    For more Enterprise Application Development news, visit eWeek