User documentation: Difference between revisions

Latest revision as of 14:09, 14 April 2021

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:

how to use your software
features of your software
tips and tricks of your software
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]

[1] ttp://www.flaticon.com/

[2] ttp://www.doc-department.com/what-are-user-documentation-and-technical-documentation/

[3] ttp://ib.compscihub.net/wp-content/uploads/2015/04/1.1.8.pdf

[1]

[2]

[3]

@@ Line 1: / Line 1: @@
 [[file:system_fund.png|right|frame|System Fundamentals<ref>http://www.flaticon.com/</ref>]]
-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<ref>http://www.doc-department.com/what-are-user-documentation-and-technical-documentation/</ref>.
+This content is used gratefully with permission from docdepartment.com<ref>http://www.doc-department.com/what-are-user-documentation-and-technical-documentation/</ref>. 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.
@@ Line 7: / Line 7: @@
 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:
+User documentation is important because it provides a avenue for users to learn:
+# how to use your software
+# features of your software
+# tips and tricks of your software
+# 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
@@ Line 14: / Line 23: @@
 * Support Portals
+== What does user documentation usually include? ==
 The list below is used with gratitude from the Dartford computer science department<ref>http://ib.compscihub.net/wp-content/uploads/2015/04/1.1.8.pdf</ref>.
-What does user documentation usually include?
 * Minimum hardware and software requirements
 * Installation guide
@@ Line 34: / Line 41: @@
 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? ==
+== Evaluating user documentation ==
-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.
+{| style="width: 95%;" class="wikitable"
+|-
+| '''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.
-Question 2: Write a plan for implementing this system. Explain your rationale.
+|-
+| '''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 ==