Types and formats of help

    Hello, Habr! Clients often come

    to us at Alconost and say, “I need a help system for my program. Make me a PeDaeFku. ” We create a user manual, draw up a PDF, and then it turns out that contextual help with the index and search was really needed.

    That is why I would like to share with all simple schemes and descriptions of the types and formats of help. I want to say right away that this material is not textbook - this classification is based on my 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 Help


    We divided the certificates into the following types according to their purpose:

    • Manuals and user instructions (operator, programmer, administrator) are classic reference documents that contain a set of instructions and a description of the software functionality depending on the user's qualifications. Designed mainly for printing (have a paper version).
    • Quick start , 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 not yet a complete guide, or they can be part of a large help (with links to the corresponding detailed descriptions).
    • Online help, WebHelp (online help) - a help that is available on the manufacturer’s website. Usually made in the style of the site. It is very convenient, since you do not need to save it on a local disk; search and keywords are built into it. Online help helps improve SEO.
    • Wiki (wiki) - a website, the structure and content of which users can independently change using the tools provided by the site itself. Pros: users write help themselves. Cons: you need to learn the wiki layout, there are difficulties when installing the wiki engine.
    • Article «How to ...» - the article (or Help topics) aimed at solving one particular problem (for example, "How to share the USB device for computers on the 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 on the network (including keywords), 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; are often located at the end of the help after the Troubleshooting section. If you anticipate most of these issues and disclose them in the help, you can significantly reduce the load on the support service. This section is recommended to be constantly updated based on letters and user reviews.
    • EULA (License Agreements), Terms of Service , Privacy Policy - sections of the reference documentation that govern the legal relationship between the manufacturer and the user, establish the responsibility of the parties, and also indicate copyright. It is better to entrust the writing of these texts to the lawyer, so that he will relieve you of the responsibility for hacking the Pentagon network with the help of your program.


    Help 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 the local computer. Usually an online help is a directory with HTML, CSS and JS files.
    • CHM - This format is mainly intended for context-sensitive help of Windows-applications (F1), CHM document consists of compressed HTML pages and illustrations. To fix problems opening CHM files downloaded from the network, you can use the free HHReg utility .
    • PDF - Help format used for printing. When exporting to this format, you need to pay attention to the CID font (it is better to set Unicode), text compression (maximum) and the format of the pictures, otherwise the final PDF file will be too large.
    • EXE (e-Book) - Windows executable file. Pros: No additional viewing software required. Cons: may contain viruses, not as good for printing as PDF; not viewable 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 primarily for documenting code.
    • ePUB is a help format intended for mobile platforms (iOS, Android, e-readers of various manufacturers). To view help files in ePUB format on a PC, you can use the free utility Adobe Digital Editions .


    How to choose the type and format of the help?


    Read the descriptions and diagrams listed above and answer your 2 main questions: “Who will read my help?”, “Where (and on what) will it be read?”. And all at once will fall into place.

    Here are a few examples of reference materials of various kinds: https://alconost.com/services/help-authoring

    I hope that we helped you make this difficult choice. We are waiting for your questions and suggestions!


    About the author

    Alconost localizes applications, games and sites in 60 languages. Native translators, linguistic testing, cloud platform with API, continuous localization, project managers 24/7, any format of string resources.

    We also make promotional and educational videos.- for sites selling, image-building, advertising, training, teasers, expliners, trailers for Google Play and the App Store.

    Read more: https://alconost.com


    Also popular now: