User documentation: Difference between revisions
Mr. MacKenty (talk | contribs) No edit summary |
Mr. MacKenty (talk | contribs) No edit summary |
||
(17 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. 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. | ||
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>. | ||
* Minimum hardware and software requirements | * Minimum hardware and software requirements | ||
* Installation guide | * 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. | 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 == | ||
{| 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. | |||
|- | |||
| '''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 == | == Standards == |
Latest revision as of 15:09, 14 April 2021
![](/images/0/01/System_fund.png)
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 |
|
|
online support |
|
|
printed manuals |
|
|
Standards[edit]
- Describe the importance of user documentation.
- Evaluate different methods of providing user documentation.