User documentation

System Fundamentals

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

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.

Now users expect the user documentation to include:

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

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

What does user documentation usually include?

• 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

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.

Do you understand this material?

A small business has a computer kiosk inside the store which allows customers to sign up for a email newsletter. If a customer signs up for a newsletter inside the store, they will get a 10% discount on their first purchase at the store. The owner hopes this 10% discount will be an incentive for customers to sign up for the email newsletter. The business will then regularly email the customers special offers and savings. The business owner expects to benefit from this system by having increased sales. The customers expect to benefit from this system by having access to special offers, to save money, and to see what is new and trendy at their store.

Question 1: Describe the importance of user documentation for the owner and then the customer.

Question 2: Evaluate different methods of providing user documentation in this case.

Do you have an advanced understanding of this material?

A school of 900 students has a secure web-based application which manages attendance data. The school administrators carefully track attendance for the students so it can identify when students have been absent for a customizable threshold. For example, the school might set a threshold of 5 absences within 30 days, which then automatically notifies the student, parent, and teacher there is a problem with attendance. The threshold might be 3 times within 10 days, or something like that. The system keeps track of attendance and tardies. The system has customizable attendance codes. For example, "absence for school trip", "excused absence", "medical absence" are all allowed absence codes.

School administrators expect to benefit by having data about attendance so they can support students and parents to be in school. School administrators also expect to benefit by giving parents and students information about attendance (so parents can support their children to be in school). Finally, school administrators expect to benefit by using attendance data to apply for government funding (as they can prove how many students were in class on a specific day).

Parents expect to benefit by knowing when their children are in school or miss school. This way parents can support their children to be in school. Being in school is a shared value between the school and the parent.

Students expect to benefit by understanding how many days of school of they have missed. The school expects students to have a strong "ownership of learning" and manage their attendance.

Question 1: Evaluate alternative installation processes.

Question 2: Write a plan for implementing this system. Explain your rationale.

Standards

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

Give a sequence of brief answers with no explanation.

Produce a plan, simulation or model.

Give a detailed account or picture of a situation, event, pattern or process.

Assess the implications and limitations; make judgments about the ideas, works, solutions or methods in relation to selected criteria.

Provide an answer from a number of possibilities. Recognize and state briefly a distinguishing fact or feature.

Use an idea, equation, principle, theory or law in relation to a given problem or issue.

Give a detailed account including reasons or causes.