User documentation: Difference between revisions

From Computer Science Wiki
No edit summary
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[file:system_fund.png|right|frame|System Fundamentals<ref>http://www.flaticon.com/</ref>]]
[[file:system_fund.png|right|frame|System Fundamentals<ref>http://www.flaticon.com/</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.  
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.
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.
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
* FAQs
Line 14: Line 23:
* Support Portals
* 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>.
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
* Minimum hardware and software requirements
* Installation guide
* Installation guide
Line 33: Line 40:


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.  
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: 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.


== Evaluating user documentation ==  
== Evaluating user documentation ==  
Line 62: Line 47:
| '''Method''' || '''Advantages''' || '''Disadvantages'''  
| '''Method''' || '''Advantages''' || '''Disadvantages'''  
|-
|-
| '''help files'''  ||  Advantage here || Disadvantage here
| '''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'''  ||  Advantage here || Disadvantage here
| '''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'''  ||  Advantage here || Disadvantage here
| '''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
|-
|-
|}
|}

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:

  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]

  1. ↑ http://www.flaticon.com/
  2. ↑ http://www.doc-department.com/what-are-user-documentation-and-technical-documentation/
  3. ↑ http://ib.compscihub.net/wp-content/uploads/2015/04/1.1.8.pdf

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

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.

Retrieved from "https://computersciencewiki.org/index.php?title=User_documentation&oldid=11101"