User documentation

From Computer Science Wiki
Revision as of 14:09, 14 April 2021 by Mr. MacKenty (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
System Fundamentals[1]

This content is used gratefully with permission from docdepartment.com[2]. Technical documentation refers to the documentation that describes how a product or service operates. For example, software code documentation, technical specifications and API documentation. Technical documentation can also describe how to install software.

User documentation refers to the documentation for a product or service provided to the end users. The user documentation is designed to assist end users to use the product or service. This is often referred to as user assistance. The user documentation is a part of the overall product delivered to the customer.

Traditionally user documentation was provided as a user guide, instruction manual or online help. However, user documentation is increasingly being delivered online today. This has enabled technical writers to be more imaginative in how they assist users.

User documentation is important because it provides a avenue for users to learn:

  1. how to use your software
  2. features of your software
  3. tips and tricks of your software
  4. how to resolve common problems with your software

Without user documentation, a user may not know how to do the above things.

Users expect the user documentation to include:

  • FAQs
  • Video tutorials
  • Embedded assistance (for example, tool tips and dynamic page content)
  • Support Portals

What does user documentation usually include?[edit]

The list below is used with gratitude from the Dartford computer science department[3].

  • Minimum hardware and software requirements
  • Installation guide
  • How to start the system
  • How to use different features of the system
  • Screenshots explaining main features of the system
  • Example inputs and outputs
  • Explanations of error messages and troubleshooting guides
  • Information to contact the developer of the system if an undocumented question arises

The quality of user documentation can affect the rate of implementation of the new system. Examples should include methods such as: help files, online support and printed manuals.

Real-world practical advice[edit]

I once heard a rumor about Steve Jobs. According to this rumor, he said "if you need to write a manual for your software, you have done something wrong". I think the point of this rumor is to design your software to be as clear as easy as possible to use. However, good user documentation can make or break the success of your product. The design, presentation, and evaluation of your user documentation is really important part of developing software. Sadly, it is also an area much-neglected, as software developers might think it is boring.

Evaluating user documentation[edit]

Method Advantages Disadvantages
help files
  • User friendly
  • really fast
  • easy to use
  • can be accessed offline
  • you might not get level of detail you want
  • the user might not know what to search for
  • Might be hard to find
online support
  • larger amount of information
  • easier to update
  • can access from any device
  • can be faster
  • can't be accessed offline
  • if you have slow internet connection, it's bad.
printed manuals
  • easy to find
  • you can browse through them
  • work without a computer
  • slower
  • if you lose it, you're going to have a bad day
  • harder to search
  • cannot be updated
  • prone to physical destruction

Standards[edit]

  • Describe the importance of user documentation.
  • Evaluate different methods of providing user documentation.

References[edit]