User's manual for software products. Examples and recommendations of convenient instructions


There are many types of provision reference information to the user - this includes FAQ (frequently asked questions, frequently asked questions) and online help and user guide (user guide) and today's popular tips (coachmarks, see example below), training videos and others.

Exist different reasons, for which you need to write a system user manual. Starting from the customer’s requests (in my practice there was a case when the customer needed to supply a user manual after each iteration, so that with its help he could carry out acceptance testing of the iteration’s functionality) and ending with the terms of the contract regarding the delivery of finished software, if we talk about software development to order. In the case of developing your own product, writing a user manual also often takes place.

An analyst is often involved in creating the manual if it is not possible to delegate it to a technical writer. In the overwhelming majority of cases, it is the analyst who has the most complete knowledge about the system; he also has the ability to clearly express his thoughts in writing due to the specifics of the profession. Therefore, I have had to deal with the creation of user manuals more than once.

Below are some practices for writing a good user manual. Some of them may be useful to someone when writing requirements specifications.

1. Standards

It is often necessary to write a document that meets the requirements of current standards. It can be:

  • IEEE Std 1063-2001, IEEE Standard for Software User Documentation";
  • GOST 19:
    • GOST 19.402-78 ESPD. Program description;
    • GOST 19.502-78 ESPD. general description. Requirements for content and design;
    • GOST 19.503-79 ESPD. Management system programmer. Requirements for content and design;
    • GOST 19.504-79 ESPD. Programmer's Guide. Requirements for content and design;
    • GOST 19.505-79 ESPD. Operator's manual. Requirements for content and design.

If the needs of the project allow you not to adhere to rigid standards, in any case, studying these documents can serve as a starting point for writing a quality document.

Yuri Kagarlitsky's book MetaGuide may also be useful. Guide for developers of technical documentation for software.

2. Structure

Think carefully about the document structure: it should cover everything functionality system, be complete and understandable.

A good user manual should contain:

  • Abstract, which provides summary contents of the document and its purpose. It is also recommended to write a short summary at the beginning of each major section.
  • Introduction, containing information on how best to use this guide.
  • Content
  • Chapters, describing how use BY
  • Glossary And
  • Subject index

The user manual may also contain:

  • FAQ and the answers to them
  • Links on Additional information according to the system
  • Chapter, describing possible Problems and ways to solve them

It is better to number all chapters and paragraphs, as well as figures and tables, so that they can be referred to within this document or from another document.

3. Users

Think about the typical users of this software: you want the document to help them solve their daily problems.

It might even make sense to make different sections (or even various documents) for different groups of users, if their interaction with the system will differ dramatically. For example, system administrators (people responsible for Accounts, access rights, etc.) will be interested in completely different functionality than ordinary users.

Respect system users, do not write instructions in a disparaging style.

4. Features of presentation

Remember that the style of presentation in oral speech or in business letter differs from this in the technical documentation, and in particular, in the user manual.

The style of the manual should be neutral and formal - the use of stylistically colored words distracts the user from the essence.

To compile good document knowledge of grammar and a little psychology will come in handy.

4.1 Write briefly and logically. Do not give unnecessary details, do not duplicate information. The sequence of mentioning information in the user manual must coincide with the sequence of user actions:

Fine: In File menu, select Saveitem.
Worse: Select Save item from File menu.

4.2 Use the imperative mood, do not use polite expressions (please, could, etc.) - excessive politeness will be a hindrance here.

Fine: Click Logout.

Worse: It is needed to click Logout to log out current user account from the system .

Worse: If user wants to log out current user account from the system(s)he needs to click Logout.

4.3 Structure information. You can often come across advice that you should try to avoid lists, however, information structured step by step is always better perceived.

Fine:
Tocreateproject:

  1. Click the Create button on toolbar.
  2. On the Create Project overlay fill in all mandatory fields.
  3. Click the Savebutton to save the project.

Worse: To create project click the Create button on toolbar, on the Create Project overlay fill in all mandatory fields, click the Save button to save the project.

4.4 Do not use future or past tense. For example, there are often manuals in which the system's reaction to a user's action is conveyed in phrases formulated in the future tense. Software has no past or future: everything happens in the present as a direct result of a specific user action. As soon as an event occurs, the software reacts.

Fine: When user clicks the Start button, the program starts the process.

Worse:When user clicks the Start button, the program will start the process.

4.5 Check the meaning of words. If you need to write a document in a foreign language, you should try as much as possible to avoid mistakes associated with insufficient knowledge of the language.

For example, the verb “press” means pressing a key on the keyboard, and “click” means pressing a button or icon in a program window using the mouse, and “hit” is generally a slang word.

Of course, spelling errors are unacceptable.

4.6 Do not use synonyms for the same term. In IT literature in English (or any other) language there is standard set verbs denoting actions (click, double-click, select, type, press, etc.) and the same standard set of control element names. Decide on terminology and stick to it throughout the document.

For example, do not allow a drop-down list in one part of the document to be called dropdown, and in another exactly the same element - combobox or dropdown list. This confuses the user.

4.7 Use abbreviations wisely and avoid jargon.

It is believed that abbreviations should not be used, but if a long term is used several times, then at the first mention in the text you should write the full name and next to it - the abbreviation in brackets, and further in the text you can use only the abbreviation. If the document has a glossary or section with abbreviations, they should be explained there.

Do not use jargon, metaphors, or terms borrowed from a language other than that of the manual.

5. Appearance

5.1 Think about the style of the document. This could be a corporate template or color scheme Software or a design specially made for the document.

When writing, feel free to highlight important things with styles or colors (for example, highlight button names in bold). But it is important to understand that incorrectly selected fonts and colors can make it difficult to perceive the content of the document.

5.2 Don't save space– break the text into short paragraphs, use relatively large headings, start new section With new page. This will make it easier for the user to read the information.

5.3 Use pictograms and illustrations. There is an opinion that you should not get carried away with illustrations, and also include icons in the text in the user manual. However graphic information is always better perceived and remembered, so screenshots and necessary icons should be present in a good manual in sufficient but reasonable quantities.

6. Support

Don't lose sight of the fact that software changes over time, which means your document must change too to stay relevant.

Conclusion

Please note that irritation from a poor-quality document may be projected onto the software by the user and thereby influence the decision to use the product.

Remember the main thing: the document should help users.

Prepared the article

Nadezhda Tarasyuk, site community member,

analyst with 6 years of experience in the field.

Eh... this is “life”!

I was convinced by personal example that writing user manuals is not such a big deal. simple task... Especially if you don’t know the software product you need to build it on!

So how do you write a user manual?

Not long ago, I got a job new job to a company engaged in the development and implementation of a software product... everything would be fine.. but I stumbled already on my first assignment..

I was given the task of writing a user manual for a program that I had never even seen before (I think it was something related to accounting, which I’m not that good at). No old versions of user manuals, no examples... just me and the program... In the process of working, I encountered some pitfalls, which I will try to describe in this article.

It would seem that it could 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” himself, or at least by a user who has been working in the system being described for a long time.

What to do if this is not so?! The first step is to run to the developer and really “sit on his neck” so that he “chews” his “brainchild” from the beginning to the very extreme level!!! In such cases, it is better to imagine yourself as a “Why” and get to the bottom of the smallest details. Unfortunately, the programmer’s nerves will not appreciate such an impulse! But here the choice is simple, either good guide, or exchange pleasantries and only...

In any case, you need to look at the program “from the outside” through the eyes of a pioneer! Having previously identified the functional modules and the module that is of greatest interest to the end user (it is best described in detail!), it is necessary to determine the level of detail of the designed manual. Usually this issue is discussed with the management of the developer organization, but it can be done at your own discretion.

In my experience, when writing a user manual it is better to spend a little time on design general structure explanatory note than to write separate manuals for each functional module later. The fact is that the more standardized (structured) the manual is, the easier it is for the user to navigate and the easier it is to describe! With a well-thought-out description structure, the probability of “forgetting” to display some key moment significantly reduced!

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

How to write a user manual:

The main guideline for writing the manual is the following description:

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

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

At the same time, you need to define menu functions, repeating field names and other functionality that are standard throughout the entire module, section of the software product, etc.

1. Brief description

2.Module A

  • Submodule A.1
  • Submodule A.2

3.Module B

  • Submodule B.1
  • Submodule B.2

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

The specifics of the fields are described, what operations are involved in filling them out, what values ​​are assigned automatically, in what cases the fields are displayed at all, the types of fields, all the buttons, checkboxes.. In general, here you can describe ad infinitum!!!

If a module contains submodules, then it is better to describe everything in a strict sequence.. I.e. at the beginning, describe the module itself (from start to finish), while making a link to the corresponding submodule, and below - describe the entire submodule in detail! It turns out enough Nice picture! The user does not have to jump from one part of the document to another and back.

And this is how the entire software product is described. At the end, you can write a list of abbreviations used when describing the user manual.

There is no doubt that this technique is generalized! But from my experience I can say for sure, it is very convenient! Convenient for the user, convenient for the developer of the user manual! Everyone is happy.. 😉

But as they say, there is no friend according to taste! We can only wish you successful developments!

See related articles

Software component of a complex or system

Goals and objectives

The User's Guide is one of the main program documents. It is impossible to imagine any complex application software product that would not be equipped with it in one form or another.

The main objective of the document is to provide users with the opportunity to independently solve all the main tasks that the program is aimed at.

User manual contains complete description of the program from the point of view of its intended use. The user manual must describe:

  • purpose of the program;
  • main challenges and opportunities;
  • way of reflecting the subject area in the program;
  • user interface programs;
  • procedure for solving basic user tasks;
  • all functions of the program and the order of their use;
  • custom program settings;
  • problems during use and ways to solve them.

When documenting small programs The user manual often includes instructions for installing, configuring, administering, updating and other maintenance of the program.

The user manual is never, or almost never, considered as teaching aid by subject area.

Methodology and style of presentation

Depending on the features of the program and the target audience, the user manual in the way the material is presented can be close to a textbook or, conversely, to a reference book. The order of presentation of material in the user manual is determined user perspective programs.

If the program is a tool that allows you to solve practical problems from a certain finite set, the manual provides standard procedures for solving each of them. For example, user mail client you need to know how to write and send a message, how to download new messages from the server, how to reply to a message, etc. Each of these actions can be broken down into successive elementary steps, at least for typical situations. In a large program like user tasks there may be many, but not infinitely many. The user manual, built on the principle of user tasks, resembles a textbook, although, as a rule, it lacks the methodological apparatus inherent in textbooks: test tasks, questions, exercises.

If the program represents an environment within which the user can solve problems assigned by him independently, the user manual should be closer to a reference book. It must consistently and systematically describe all the functions of the program and the order of their use. What to do with them, what to direct them to, the user will think for himself (or sign up for training courses). So, in the user manual for the graphic editor we will find a description of all graphic primitives, tools, filters, however, it will not directly say how to depict a building, a car or, say, a dog. The user either knows how to draw or not.

Other user perspectives are possible. There are programs through which the user controls the state of a particular object, say, an industrial installation. Then the user manual is built on the principle of a table: the program message - the reaction or possible reactions of the user.

If the user uses the program to solve problems in non-trivial subject areas, it is highly recommended to include a concept section in the user manual. It should describe the way the program implements representation of real-world objects, so that the user has a good understanding of which of them and at what level of abstraction he can work.

Typical structure

Due to the great variety of programs, it is difficult to imagine a universal user manual structure. In each specific case, it will be mainly determined by the features of the program being described. However, the structure of the user manual is usually similar to the one below.

  1. General information.
  2. Installation and initial setup.
  3. Basic concepts and definitions.
  4. User interface.
  5. Working with the program.
  6. Custom setting.
  7. Error messages.

A single section “Working with the program” is often replaced by several successive sections describing large groups of user tasks or functions.

Peculiarities

Due to a historical incident, the user manual is not provided for by domestic standards for software documentation (ESPD). Of those described in the ESPD, the document closest to it in purpose and content is the operator's manual. However, it must be understood that the operator, which is meant in the ESPD, has little in common with the user in the current understanding.

@ Zhuravlev Denis

Many IT companies that develop and support software and automated systems, are faced with the task of creating user documentation for their products in accordance with GOST requirements.

As a rule, the need for documentation in accordance with GOST arises in cooperation with government organizations, large industries and companies, in the custom development of software for tenders and government orders, or if it is necessary to add a software product to the " Single register Russian programs for electronic computers and databases (register of domestic software)".

There are two series (sets) of standards that regulate the set created documents and rules for their design when developing automated systems, complexes and software:

On the one hand, these two standards compete with each other, I suggest various options completeness of project documentation. On the other hand, they focus on different aspects and therefore complement each other well.
GOST 34 mainly determines the completeness, types, structure and content of documents created.
GOST 19 largely determines the rules for drawing up documents.
Therefore, in practice, both of these GOSTs are often used at once.

If we talk specifically about documentation for the end user of the system, then from the list of documents described in GOST 34 we are interested in the “User’s Guide”. In GOST 19, a document similar in meaning is called the “Operator’s Manual”, but for software it is the first option that is most often used.

A user manual comes with any product, program, or system. It should provide the user with information about the properties of the product, its functionality, how to use it and how to work with it.

For a novice technical writer or a simple specialist who is unexpectedly tasked with preparing a GOST user manual, this task is a serious problem.

Not only does it need to be studied big number regulatory documents, abounding cross references and written in complex, overly clerical, almost legal language, it is still necessary to select from there the requirements that relate specifically to the type of document being created. Then, throughout the work, you need to constantly monitor compliance with these requirements in the working document, constantly checking the standards.

Usually the problem is aggravated by a lack of time, since writing user documentation, unfortunately, is often customary at the very end of the project, before the very deadline - the date of delivery or launch of the system.

For an experienced technical writer, documenting according to GOST may not cause serious difficulties. However, even for him, preparing templates for new documents, bringing existing documentation to the requirements of standards, or checking the final document for compliance with these requirements can take significant time.

Dr.Explain simplifies the creation of a user manual according to GOST

Starting from version 5.5.1100, the program for creating user documentation Dr.Explain offers the function of automated GOST support in projects. This function is designed to make life much easier for users who are faced with the task of creating a user manual in accordance with the requirements of government standards.

In particular, the Dr.Explain program controls and automates support for the following standard requirements:

  • Availability of mandatory sections of the document “User Guide” [GOST 34 RD 50-34.698-90]. All sections are provided with explanations of their content.
  • Design of title pages, annotations and contents [GOST 19.105-78, 19.104-78].
  • Parameters of printed pages of a document and the location of the main elements on them [GOST 19.106-78].
  • Structure and design of headers and footers [GOST 19.106-78].
  • Design of the text part of the document: font styles, paragraph indentations, line spacing[GOST 19.106-78].
  • Formation and design of headings, sections, enumerations (lists) [GOST 19.106-78].

Managing the GOST support function for a project is available in Project Settings in the section Are common.

When GOST support mode is enabled for the project, the corresponding custom settings for printed formats RTF\DOC and PDF are automatically overlapped by the program, which guarantees full compliance of the parameters of the output documents with the requirements of the standards.

For HTML and CHM output formats, custom settings will be used regardless of whether GOST support mode is active. This removes the restriction on free styling of these formats and allows, for example, to design an online help completely in a corporate or thematic style.

Important:

Important: The GOST support function is available in Dr.Explain only in Russian version interface. The program interface language is selected in the menu Settings\Selecting program language (Options\Application language).

Creation of a new user manual according to GOST

To create a new user manual according to the requirements of GOST 34 in the Dr.Explain program, you can use menu commands File\Create local project - User Guide according to GOST 34 or File \ Create a common project on tiwri.com - User Guide according to GOST 34

or similar buttons on the application start screen.

The program will create new project, which already contains the template title page, abstract, table of contents and mandatory sections, formatted according to GOST.

The text of each section will provide a brief instructional hint on what needs to be included in that section. The user only needs to fill the sections with relevant content.

Design settings for printed formats RTF/DOC and PDF will be set in accordance with the requirements of GOST 19.

Bringing existing user documentation into compliance with GOST requirements

Also, the Dr.Explain program allows you to bring existing user documentation in accordance with GOST requirements.

Important: Before enabling the GOST support mode for projects that already exist in the Dr.Explain format, you must do backup copy gui file of the project.

If the source documentation is not yet maintained in Dr.Explain, but is stored in other formats, the first step is to import existing documents into the program. Dr.Explain supports importing documents from a number of popular formats. Import commands are available both in the program’s start window and in the menu File.

Then you need to enable the GOST support mode in the project properties in the manner described earlier. The program will check the document structure for the presence of required sections and, if they are missing, will create them. Rest existing sections, the presence of which is not regulated by GOSTs, will be moved to the section “hidden from export” Old partition tree”.

The user will need to drag-n-drop the contents of these sections or entire sections into the main project tree and edit them as necessary.

As in the first case, the design settings for printed formats RTF/DOC and PDF will be set in accordance with the requirements of GOST 19.


You will need

  • - 100% knowledge of the device or software product for which the manual is being written;
  • - knowledge in the field of linguistics;
  • - writing skills.

Instructions

Management user or, in other words, an instruction manual is a document intended to provide assistance in using some system of its user m. To compile the manual user you need to know the system being described one hundred percent, but look at it through the eyes of someone who knows nothing. Let's assume the leadership user for a certain software utility that has no analogues yet. Imagine that you are encountering this program for the first time. Where should you start? What do you need to know first? Organize this knowledge into categories of importance.

By dividing all the information related to your creation into groups, you have made a plan for writing a manual user. Start describing the work in your program from the basics, leaving for last the most complex details regarding, say, reprogramming features or working with critical errors. At this point you should have the contents of the guide ready. user– one of the mandatory parts of this document.

If the manual you are creating is intended for use in a large company, then you should pay attention to the corporate standards adopted there. For example, in many Russian companies User manuals are not accepted without illustrative support, in other words, pictures explaining what is written. In the manual user in addition to the content, there must be other mandatory parts: - Abstract, that is, an explanation of the general objectives of the manual and the product being described; - introduction, which talks about those related to the manual user documents and how to use the manual; - sections explaining the use of the product at different stages of its use, such as first steps, repair or maintenance; - a section for frequently asked questions and answers to them; - a glossary or .

Usually by creating a manual user a technical writer is a person who has all the necessary knowledge of both the language and the product being described. When engaging in the activities of a technical writer without proper training, you need to remember a few rules. Firstly, one should not overuse special terms that are not understandable to the average person. user. Secondly, each term used must be described and explained in detail. Thirdly, you need to write as clearly and concisely as possible. Finally, a technical writer must be able to look at his own writing through the eyes of an ordinary person. user to see the shortcomings of your own text.


2024 gtavrl.ru.