Types and formats of references
Hi, Habr!
Customers often come to Alconost and say, “I need a help system for my program. Make Me PeDedekku ”. We create a user manual, draw up a PDF, and then it turns out that we really needed contextual help with the index and search.
That is why I would like to share with all simple outlines and descriptions of types and formats of help.
')
Just want to say that this material is not a textbook - this classification is based on its own experience. I think that the post will be useful to anyone who wants to create a new help or improve an existing one.
We have divided the information into the following types of purposes:
Depending on the type of certificate and its location, one or several formats are selected:
Familiarize yourself with the above descriptions and diagrams and answer yourself to two main questions: “Who will read my certificate?”, “Where (and what) will it be read?”. And everything will immediately fall into place.
And here are some examples of reference materials of various kinds: https://alconost.com/services/help-authoring
I hope that we have helped you to make this difficult choice. We are waiting for your questions and suggestions!
about the author
Alconost is engaged in the localization of applications, games and websites in 60 languages. Language translators, linguistic testing, cloud platform with API, continuous localization, 24/7 project managers, any formats of string resources.
We also make advertising and training videos - for websites selling, image, advertising, training, teasers, expliners, trailers for Google Play and the App Store.
Read more: https://alconost.com
Customers often come to Alconost and say, “I need a help system for my program. Make Me PeDedekku ”. We create a user manual, draw up a PDF, and then it turns out that we really needed contextual help with the index and search.
That is why I would like to share with all simple outlines and descriptions of types and formats of help.
')
Just want to say that this material is not a textbook - this classification is based on its own experience. I think that the post will be useful to anyone who wants to create a new help or improve an existing one.
Types of references
We have divided the information into the following types of purposes:
- Manuals and user instructions (operator, programmer, administrator) are classic reference documents that contain a set of instructions and a description of software functionality depending on the user's qualifications. Designed mainly for printing (have a paper version).
- Quick start , Getting started ( Getting Started) - small (up to 10 sheets) manuals, the purpose of which is to quickly learn how to use the product and get the final result. They can be created while there is no complete manual, or they can be part of a large help (with links to the corresponding detailed descriptions).
- Online help, WebHelp (Online Help) - help, which is available on the manufacturer's website. Usually made in the style of the site. It is very convenient, because you do not need to save it on a local disk, search and keywords are built into it. Online help helps improve SEO.
- A wiki is a website whose structure and content can be modified by users using the tools provided by the site itself. Pros: users themselves write help. Cons: it is necessary to study wiki markup, difficulties arise when installing a wiki engine.
- The articles “How to ...” are articles (or sections of reference) aimed at solving one specific task (for example, “How to share a USB device for computers on a local network?”). As a rule, such articles contain a specific sequence of actions with several screenshots, a description of possible problems and their solutions. These texts can be used for placement in the network (including keywords in them), which contributes to the promotion of the product. At the end of the How to article you can post a training video.
- FAQ (FAQ) - questions and answers to them; often located at the end of the help section after the Troubleshooting. If you anticipate most of these questions and reveal them in the certificate, you can significantly reduce the load on the support service. This section is recommended to constantly update, based on the letters and user reviews.
- EULA (License Agreements), Terms of Service (Terms of Use), Privacy Policy (Privacy Policy) - sections of reference documentation that regulate the legal relationship between the manufacturer and the user, establish the responsibility of the parties, as well as specify the copyright. It is better to entrust the writing of these texts to a lawyer so that he will save you from responsibility for the fact that with the help of your program the Pentagon network was hacked.
Reference Formats
Depending on the type of certificate and its location, one or several formats are selected:
- DOC (RTF) - A common format for documentation. If you want to open help on any platform and import into various editors, then translate it into RTF format.
- HTML - Format for online help. It can also be opened on a local computer. Usually the online help is a directory with HTML, CSS and JS files.
- CHM - This format is intended primarily for context-sensitive help for Windows applications (F1), a CHM document consists of compressed HTML pages and illustrations. To troubleshoot problems opening CHM files downloaded from the network, you can use the free utility HHReg .
- PDF - Help format used for printing. When exporting to this format, you need to pay attention to the CID font (it is better to use Unicode), text compression (maximum) and image format, otherwise the final PDF file will be too large.
- EXE (e-Book) - executable Windows file. Pros: no additional software required for viewing. Cons: may contain viruses, is not as good for printing as PDF; not viewed on Mac.
- HXS (MSHC) - Help formats for Visual Studio (MS Help 2 and MS Help 3 engines). Files are zip-archives with html files and images. Used mainly to document the code.
- ePUB is a help format designed for mobile platforms (iOS, Android, book-readers of various manufacturers). To view help files in ePUB format on a PC, you can use the free Adobe Digital Editions utility.
How to choose the type and format of help?
Familiarize yourself with the above descriptions and diagrams and answer yourself to two main questions: “Who will read my certificate?”, “Where (and what) will it be read?”. And everything will immediately fall into place.
And here are some examples of reference materials of various kinds: https://alconost.com/services/help-authoring
I hope that we have helped you to make this difficult choice. We are waiting for your questions and suggestions!
about the author
Alconost is engaged in the localization of applications, games and websites in 60 languages. Language translators, linguistic testing, cloud platform with API, continuous localization, 24/7 project managers, any formats of string resources.
We also make advertising and training videos - for websites selling, image, advertising, training, teasers, expliners, trailers for Google Play and the App Store.
Read more: https://alconost.com
Source: https://habr.com/ru/post/160687/
All Articles