Useful Tips

How to create a user manual

User's manual - a document whose purpose is to provide people with assistance in using some system. The document is part of the technical documentation for the system and, as a rule, is prepared by a technical writer.

Most user manuals contain images in addition to text descriptions. In the case of software, screenshots are usually included in the manual; in the description of equipment, simple and understandable drawings. The style and language used are available to the intended audience, the use of jargon is reduced to a minimum or explained in detail.

Standards

A typical instruction manual contains:

  • An annotation that summarizes the contents of the document and its purpose
  • An introduction containing links to related documents and information on how to best use this guide.
  • Content Page
  • Chapters that describe how to use at least the most important system features
  • Chapter describing possible problems and solutions
  • Frequently Asked Questions and Answers
  • Where else to find information on the subject, contact information
  • Glossary and, in large documents, subject index

All chapters and paragraphs, as well as figures and tables, are usually numbered so that they can be referenced inside a document or from another document. Numbering also facilitates links to parts of the manual, for example, when a user communicates with a support service.

Standards

The structure and content of the document User's manual automated systems are regulated by subsection 3.4 of RD 50-34.698-90. The structure and content of documents Operator Manual, Programmer's Guide, System Programmer Guide GOST 19.505-79, GOST 19.504-79 and GOST 19.503-79 are regulated respectively.

  • A set of standards and guidelines for automated systems (GOST 34)
    • RD 50-34.698-90 AUTOMATED SYSTEMS. REQUIREMENTS FOR THE CONTENT OF DOCUMENTS
  • The unified system of design documentation (ESKD) defines the document “Operation Manual” and other documents:
  • The unified system of program documentation (ESPD) defines the documents "Operator's Guide", "Maintenance Manual" and their structure:
    • GOST 19.101-77 Types of programs and program documents
    • GOST 19.105-78 General requirements for program documents
    • GOST 19.505-79 Operator Manual. Content and Design Requirements
    • GOST 19.508-79 Maintenance Manual. Content and Design Requirements

How to write a user manual

Reply Analytics September 23rd, 2010 Analyzer

Eh ... here it is "life"!

I was convinced by a personal example that writing user manuals is not such an easy task ... Especially if you do not know the software product on which you need to compile it!

So how do you write a user manual?

Not so long ago, I got a new job at a company developing and implementing a software product ... everything would be fine .. but I stumbled on my first assignment ..

My task was to write a user manual for a program that I had never seen before (it seems to be something from accounting, which I’m not so good at). No old versions of user manuals, no examples .. only me and the program .. In the process, I came across some pitfalls that I will try to describe in this article.

It would seem that it can be difficult! There is a program .. a little brainstorming - and everything is done. Of course, the most ideal option is if the user manual is written by the developer of the "miracle of nature", or at least a user who has been working in the described system for a long time.

And what if it is not so ?! The first step is to run to the developer and thoroughly “sit on his neck” so that he “chews” his “brainchild” from the very beginning to the highest level. In such cases, it is better to imagine yourself "Pochemuchka" and dig into the smallest detail. Unfortunately, the nerves of the programmer will not appreciate such an impulse! But here the choice is simple, either good leadership, or an exchange of courtesies, and only ...

In any case, you need to look at the program “from the side” through the eyes of a pioneer! Having previously selected the functional modules and the module that is of most interest to the end user (it’s best to describe max in detail!), It is necessary to determine the level of detail of the projected guide. Usually this issue is discussed with the leadership of the organization-developer, but it is also possible at your own discretion.

From my own experience, I can say that when writing a user manual it is better to spend some time designing the general structure of an explanatory note than then writing separate manuals for each functional module. The fact is that the more standardized (structured) the manual, the easier it is to navigate the user and describe it easier! With a well-thought-out structure of the description, the probability of “forgetting" to display some key point is significantly reduced!

There is still such a good moment - these are GOSTs! To describe user manuals, there is such a wonderful GOST as GOST 19.505-79 (description see in the site section).

How to write a user manual:

The main guideline for writing this guide is the following description:

  • the purpose of the program (why is it needed at all, who is it oriented to, etc.),
  • messages to the operator (description of possible errors, user messages, etc.).
  • program execution conditions (min and max hardware and software requirements),
  • program execution (description of program functionality, sequence of operator actions, etc.),

As an example, I can offer my own methodology for describing program execution. In the beginning, you need to analyze the entire described software product and determine the breakdown of individual modules (sections, etc.).

In parallel, you need to define menu functions, repeating field names and other functionality that are standard across the module, section of the software product, etc.

Next, we form the following structure:

The “Short Description” section contains a brief description of modules A and B, and also describes those repeating menu items, field names, etc., typical for both modules. Further, in the description of the module / submodule itself, a brief algorithm for working with the module / submodule (loading, viewing, adding, editing, deleting, generating reports, etc.) is described, after which a more detailed description of all the functionality and all available fields is carried out .. In other words all in detail!

The specifics of the fields are described, with what operations their filling is connected, what values ​​are assigned automatically, in which cases fields, field types, all buttons, checkmarks are generally displayed. In general, it can be described indefinitely.

If a module contains submodules, then it is better to describe everything in a strict sequence .. Those. at the beginning, describe the module itself (from beginning to end), at the same time make a link to the corresponding submodule, and below, describe in detail the entire submodule! It turns out pretty beautiful picture! The user does not have to skip from one part of the document to another and vice versa ..

And so the entire software product is described. In the end, you can write a list of abbreviations used in the description of the user manual.

There is no doubt that this technique is generalized! But from my experience I can say for sure, very convenient! User-friendly, user-friendly developer guide! Everyone is happy .. 😉

But as they say, the taste and color of a friend is not! It remains to wish successful development!