User documentation

System Fundamentals

User documentation describes how to use your software. User documentation should be written for non-technical users. 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: Evaluate alternative installation processes.

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

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.

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

Give a detailed account including reasons or causes.

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 or picture of a situation, event, pattern or process.