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 software according to which it needs to be compiled!

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 leadership, or an exchange of pleasantries and nothing more...

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, rather than later writing separate manuals for each functional module. 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 likelihood of “forgetting” to display some key point is 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

@ Zhuravlev Denis

Many IT companies that develop and maintain 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:

• GOST 34 - Automated systems
• GOST 19 - Unified system program documentation(ESPD)

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 is it necessary to study a large 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 indents, 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 a title page template, 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.

There are many types of providing reference information to the user - these are FAQ (frequently asked questions, frequently asked questions), 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 structure of the document: it should cover all the functionality of the 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 software color scheme, or a design specifically 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 the necessary icons should be present in good leadership 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.

In the section Sources used in the development, indicate a list of scientific and technical publications, regulatory and technical documents and other scientific and technical materials that are referenced in the source text.

The explanatory note is compiled by professionals in the field of software development and for specialists of the same skill level. Therefore, it is appropriate to use special terminology, refer to special literature, etc.

11.3. User guide

As mentioned above, currently another operational document is often used, which partly includes the guidance of the system programmer, programmer and operator. This document is called the User's Guide. The appearance of such a document was a consequence of the widespread dissemination personal computers, working on which users combine the three specified specialists.

Drawing up documentation for users has its own characteristics due to the fact that the user, as a rule, is not a professional in the field of software development. The book by S. J. Grimm gives recommendations for writing such program documentation:

take into account the interests of users - the manual must contain all the instructions necessary for the user;

be clear and use short sentences;

avoid technical jargon and highly specialized terminology; if it is still necessary to use some terms, they should be explained;

be precise and rational - long and confusing manuals are usually not read by anyone, for example, it is better to provide a drawing of a form than to describe it at length.

The user manual usually contains the following sections:

general information about the software product;

installation description;

launch description;

operating instructions (or description user interface);

messages to the user.

Chapter General information About the program usually contains the name of the software product, a brief description of its functions, implemented methods and possible areas of application.

The Installation section usually contains a detailed description of the steps to install the software product and the messages that may be received during this process.

The Launch section, as a rule, describes the steps to launch the software product and the messages that may be received.

Chapter Operating Instructions usually contains a description of operating modes, input/output formats, and possible settings.

Chapter Messages to the user must contain a list of possible messages, a description of their content and actions that must be taken in response to these messages.

11.4. System Programmer's Guide

According to GOST 19.503-79, the system programmer's manual must contain all the information necessary to install the software, configure it and test its functionality. In addition, as mentioned above, it often includes a description of the required maintenance, which was previously provided in the operator’s manual (GOST 19.505-79) and/or manual maintenance(GOST 19.508-79). Currently this diagram used to compile a system administrator's guide.

The system programmer's manual should contain the following sections:

General information about the software product,

structure,

setting,

examination,

additional features,

messages to the system programmer.

The General information about the program section should include a description of the purpose and functions of the program, as well as information about technical and software that ensure the execution of this program (for example, the volume random access memory, requirements for the composition and parameters of external devices, software requirements, etc.).

In chapter Program structure information about the structure of the program must be provided,

her components, connections between components and about connections with other programs.

The section Setting up the program should contain a description of the steps to set up the program for the conditions of practical use.

The section Testing the program should contain a description of ways to check the functionality of the program, for example, test examples.

In chapter Additional features a description of the additional features of the program and how to access them should be provided.

In chapter Messages to the system programmer The texts of messages issued during configuration and testing of the program, as well as during its execution, a description of their content and the actions that must be taken in response to these messages must be indicated.

11.5. Basic rules for preparing software documentation

When preparing text and graphic materials included in the program documentation, you should adhere to current standards. Some provisions of these standards are given below.

Design of text and graphic material. Text documents are drawn up on A4 size sheets, while graphic swearing can be presented on A3 size sheets. The margins on the sheet are determined in accordance with the general requirements: left - at least 30, right - at least 10, top - at least 15, and bottom - at least 20 mm. In text editors for designing a note, page parameters are ordered depending on the printing device. When manually completing documents, page parameters are selected for convenience.

All pages are numbered continuously. The number is indicated on the top right with an Arabic numeral. Pages include both sheets with texts and pictures, and sheets of applications. The first page is considered to be the title page. Page number on title page They don’t put it down.

The names of the sections are written in capital letters in the middle of the line. The distance between headings and text, as well as between section and subsection headings, should be equal to:

when executing a document by typewriting - two intervals;

when done handwritten - 10 mm;

using text editors- determined by the editor's capabilities. The names of subsections and paragraphs should be placed with paragraph indentation and print

out of order with a capital letter, without underlining and without a period at the end. Distance between last line the text of the previous section and the subsequent heading, when located on one page, should be equal to:

when executing a document by typewriting - three intervals;

when done handwritten - at least 15 mm;

when using text editors - determined by the capabilities of the editor.

Sections and subsections are numbered in Arabic numerals with a dot. Sections must have serial numbers 1, 2, etc. The subsection number includes the section number and the serial number of the subsection included in this section, separated by a dot. For example: 2.1, 3.5. References to paragraphs, sections and subsections indicate, using the serial number of the section or paragraph, the

example, “in Sect. 4", "in clause 3.3.4".

The text of sections is printed at 1.5-2 intervals. When using text editors, the height of letters and numbers must be at least 1.8 mm (fonts No. 11-12).

Listings should be numbered in Arabic numerals with a bracket, for example: 2), 3), etc. - with a paragraph indent. It is allowed to highlight an enumeration by placing a hyphen before a text item or a symbol that replaces it in text editors.

Design of drawings, algorithm diagrams, tables and formulas. In accordance with GOST 2.105-79 “General requirements for text documents,” illustrations (graphs, charts, charts) can be given both in the main text and in the appendix. All illustrations are called drawings. All figures, tables and formulas are numbered in Arabic numerals sequentially (continuous numbering) or within a section (relative numbering). In the application - within the application.

Each drawing must have a caption - a title placed under the drawing, for example:

Fig. 12. Main menu window shape

All figures, tables and formulas in the note must have links in the form: “(Fig. 12)” or “the form of the main menu window is shown in Fig. 12".

If space permits, figures and tables should be placed immediately after the paragraph in which they are first mentioned, or as close as possible to that paragraph on subsequent pages.

If a drawing occupies more than one page, all pages except the first are marked with the drawing number and the word “Continuation.” For example:

Rice. 12. Continued

Figures should be placed so that they can be viewed without turning the page. If such placement is not possible, the pictures should be positioned so that to view the page must be rotated clockwise. In this case, the top edge is the left edge of the page. The location and size of the fields are preserved.

Algorithm diagrams must be made in accordance with the ESPD standard. The thickness of the solid line when drawing algorithm diagrams should be from 0.6... 1.5 mm. Inscriptions on diagrams must be made in drawing font, the height of letters and numbers must be at least 3.5 mm.

The table number is placed in the right top corner or before the table header, if there is one. The title, except for the first letter, is written in lowercase letters.

The test results are shown in table. 4.

The formula number is placed on the right side of the page in parentheses at the formula level. For example:

z: =sin (x)+In (y);

Design of applications. Each attachment must begin on a new page with the word “APPENDIX” in capital letters in the right corner and have a subject heading. If there is more than one application, they are all numbered in Arabic numerals: APPENDIX 1, APPENDIX 2, etc. For example:

APPENDIX 2

Title page of the settlement and explanatory note

Figures and tables placed in the appendix are numbered in Arabic numerals within each appendix with the addition of the letter “P”. For example:

Rice. Item 12 - 12th drawing of the application; Rice. Sh.2 - 2nd picture of the 1st appendix.

If the application contains the text of the program, then each file is designed as a drawing with the name of the file and its purpose, for example:

Rice. P2.4. File menuran.pasprogram for cursor movement of the main menu.

Making a list of references. The bibliography should include all sources used. Information about books (monographs, textbooks, manuals, reference books, etc.) must contain: the surname and initials of the author, title of the book, place of publication, publisher, year of publication. If there are three or more authors, it is allowed to indicate the surname and initials of only the first of them with the words “etc.” The publishing house must be cited in full in the nominative case: abbreviation of the name of only two cities is allowed: Moscow (M.) and St. Petersburg

Information about an article from a periodical must include: the surname and initials of the author, the name of the article, publication (magazine), series (if any), year of publication, volume (if any), number of the publication (magazine) and page numbers on which it is placed article.

11.6. Rules for preparing calculation and explanatory notes for course design

When preparing explanatory notes, you should adhere to GOST 7.32-91 (ISO 596682) “Report on research work. Structure and design rules." According to this standard Text Document this type should include:

title page,

abstract,

content,

introduction,

the main part,

conclusion,

list of sources used, including literature,

applications.

The title page is drawn up in accordance with GOST 19.104-78 “Unified system of program documentation. Basic inscriptions" (Fig. 11.1).

The second page is an abstract or summary of the software product being developed. The abstract in a condensed form should contain information about the volume of the document, the number of illustrations, appendix tables, etc., as well as a list keywords and the main provisions of the document. For example, for a report on research work: description of the research object, goals of the work, research methods and equipment, results obtained, recommendations for implementation, etc. The annotation also briefly describes the purpose and features of the development, but it usually does not include information about volume, etc.

Third page - contents, including: introduction, names of all sections, subsections, paragraphs, conclusion, lists of references and applications indicating page numbers. Neither the annotation or abstract, nor the content itself is mentioned in the table of contents.

Then the sections of the document follow in the order determined by the logic of the presentation of the material. This may be followed by appendices containing material not included in the document due to its limited volume, but interesting for a deeper understanding of the material presented.

As an example, consider the table of contents of the explanatory note for the project for the course “Programming Technology”.

Introduction........................................................ ........................................................ ...............................................
1.Choice of technology, language and programming environment.................................................... ............................
2.Analysis and clarification of requirements for the software product.................................................. .............
2.1.Analysis of the information processing process and selection of structures
data for its storage ..................................................... ........................................................ ..............
2.2.Selection of methods and development of basic algorithms for solving the problem....................................
3.Development block diagram software product........................................................ .............
4.User interface design.................................................... .......................................
4.1.Construction of a dialogue graph.................................................... ........................................................ .......
4.2.Development of information input-output forms.................................................... ...........................
5.Designing domain classes............................................................ ........................................
5.1.Constructing a class diagram.................................................... ...................................................
5.2. Clarification of the structure of domain classes
and development of method algorithms.............................................................. ............................................
6.Selection of testing strategy and test development.................................................. ...........................
Conclusion................................................. ........................................................ ........................................
Bibliography................................................ ........................................................ ............................
Appendix 1. Technical specifications.................................................... ........................................................ ..
Appendix 2. User's Guide................................................... ...........................................

Control questions

1.Name the main types of software documentation. Describe each of them. In what cases are they used?

2.What should be described in explanatory note? Who is it intended for? Why do explanatory notes usually describe not only the decisions made, but also the rejected options?

3.Who is the user manual intended for? What should it contain? In what situations do you read the user manual? Think back to the user manuals you've read. What didn't you like about them?

APPLICATION

System symbols Unified Modeling Language (UML)

Unified Modeling Language UML - in fact standard remedy descriptions of projects created using an object-oriented approach. The software project model, as intended by the language authors, may include a large number of diagrams various types using unified system notation. Among the diagrams, the most commonly used are:

use case diagrams or precedents (uses case diagrams) - show the main functions of the system for each type of user;

class diagrams(class diagrams): contextual, descriptions of interfaces and implementations - demonstrate the relationships of classes with each other;

activity diagrams(activity diagrams) - represent a diagram of control flows for solving a certain task using individual actions; they allow the presence of parallel and/or alternative actions;

interaction diagrams(interaction diagrams) of two alternative types:

a) sequence diagrams (sequence diagrams) - display the time-ordered interaction of objects during the execution of a use case,

b) cooperation diagrams(collaboration diagrams) - provide the same information as sequence diagrams, but in a form that allows you to better represent the responsibilities of classes as a whole;

object state diagrams(statechart diagrams) - show the states of an object and the conditions for transitions from one state to another;

package diagrams(package diagrams) - demonstrate the relationships between sets of classes combined into packages;

component diagrams(component diagrams) - show what software components it consists of software and how these components are related to each other;

placement diagrams(deployment diagrams) - allow you to connect software and hardware components of the system.

Supplements to the diagrams are formalized and informal text descriptions, comments and dictionaries.

When constructing these and other diagrams, a unified notation system is used. The designations of the precedent diagrams are given in table. Item 1, class and package diagrams - in table. Item 2, interaction diagrams - in table. P3, diagrams of activities and states of the object - in table. Item 4, diagrams of components and placement - in table. P.5. If necessary, it is allowed to use the designations of some diagrams on others.

Creating a new product (online service, online store, mobile app), we strive to ensure the reliability, performance and safety of the product. To stand out from competitors, we create an unusual design and add new features to the interface. Based on our own experience, we believe that users will understand all the innovations.

But in most cases non-standard solutions lead to loss current users and increase the cost of attracting new ones.

Why are expectations not equal to results after launching a project?

Observations of the promotion of different online services show almost the same results. If, after launching the service, we survey the first 100 users, we will get something like this:

• 40 people will not use the service until they read the instructions, screenshots and videos created by the service consultants. They will contact technical support for instructions;
• 20 people will independently read the instructions and study the functions of the service;
• another 20 will not understand where to start and will not use the service;
• only 10 users will complete all the settings correctly, I will not read the instructions and contact the service technical support;
• the remaining 10 people evaluated the service, compared it with competitors, until they decided whether they would use it.

Most users do not understand the functions and navigation of the online service; 40% of users do not read instructions on the website and turn to consultants for help. Only 10% start working with the service without additional help, because they have the necessary user experience.

How to make the service more understandable

Well-known usability expert Jakob Nielsen argues that “a system should be equally acceptable to two groups of users - novices and experienced” (the principle of flexibility and efficiency, one of the “10 heuristics of user interface design”).

Both beginners and experienced users will understand the clear system equally quickly. If the developer designs the interface based on his own experience, few will be able to use the solution. There are not many specialists with experience of the same level :-)

If beginners do not understand how the service works without instructions and contacting technical support, find a way to explain to them how to use the system correctly. To begin with, analyze what exactly people don’t understand and what questions they ask. Then write clear instructions and place hints in the right places.

What novice users ask about

New users ask two questions:

1. Where to start to use the service? (the user does not understand the service well).
2. How to complete this or that task? (does not understand the sequence of actions, the work scenario).

This data means that users do not receive necessary information from instructions and manuals for working with the service:

• The user did not find the instructions.
• The user did not understand the multi-page documentation.

Jakob Nielsen formulated the rule back in 1995: “it is best if the system can be used without reading the documentation, but if necessary, you need to provide background information that should not be too voluminous and should offer a list of specific actions.”

Provide users with accessible and understandable instructions

“10 Heuristics for User Interface Design” by Jakob Nielsen contains a number of recommendations and rules for designing user instructions.

We've adapted these tips.

Good reference article	Bad help article
Contains clear descriptions of the steps that will lead the user to the goal	Invites the user to independently identify the problem and select a solution from the list
Offers instructions to solve only the current task Click “OK” and your letter will go to the recipient	Contains a list of tips related to at this stage working with the system: To write a letter, click “Create” To delete a letter, click “Add to Trash” To send a letter - click "OK"
Placed in a prominent place, appears if the user has visited the site and does not perform any actions for 10 seconds	Hidden in the “Site Help” section, which no one reads
Fits in several sentences	Contains many pages and links

The rules of the American usability specialist are supplemented by a Russian specialist, author of the book “Shareware: Professional Development and Promotion of Programs” Stanislav Zharkov:

“When describing a way to solve a problem, as when writing any documentation, you need to avoid writing too long texts, because users will simply skim through them without delving into the meaning of what is written, just as a person looking through a newspaper first stops looking on short notes, skipping longer materials. It's best to write something like step by step instructions, each step of which is 1-2 sentences” (“Shareware: professional development and promotion of programs”, St. Petersburg, 2001).

Short and clear instructions are easily implemented in the form of hints. The user more easily perceives small tips for key actions and learns how to work with the system faster.

Creating instructions using hints

We looked at users' reactions, recorded and studied their questions, and identified functions they did not understand. For each unclear moment we will create short hints.

Well-known companies, such as Google and Facebook, help users with tips. You've met them if you created them on Facebook page companies or worked with text in Google Docs.

And this is an example of a hint for users Google Plus .

Brief instructions in tooltips alert users to new or additional features. The system automatically shows them to new users when they start working. They are displayed only once, you can close (skip) them, or go to the help section of the resource and read more. To explain the sequence of actions, service developers combine such tips into demo tours. Similar instructions are offered to their Google users Plus and Youtube.

Checklist for developing effective instructions in the form of tips

1. Describe specific user steps with hints.

2. Create training tours for job scenarios.

3. Explain the purpose with hints complex functions and special terms.

4. Tell users how to speed up frequently repeated actions.

5. Show tooltips automatically only once, on the user's first visit.

6. Allow the user to enable demo tours at any time.

7. Design the tips in a uniform design for the service.

Tools for creating tooltips

Ready-made libraries are suitable for creating one-page instructions (for one interface window) Java code Script: Intro.js and Bootstro.js. The services Hintarea and Walkme.com are suitable for creating cross-page hints.

Tips can help those who:

• installed a new mobile application;
• used an online service (booking system, notice board);
• places an order in the online store;
• works with a business application (CMS, CRM).

Example: Tips for training CMS Wordpress users

Let's imagine typical situation. The web studio developed the website and handed it over to the owner company. The company manager will fill the site with content. Most likely, he does not have serious experience working with a CMS (let it be WordPress in our example). The administration panel will ask him a number of questions:

• where to start;
• what the names and terms mean;
• where to find reference information;

The web studio will make it much easier for clients to work with the site if it creates hints for them in difficult places in advance.

You can come up with dozens of tips and combine them into demo tours, so as not to force the user to scroll through pages of documentation or watch video tutorials. To understand what kind of tips there are, we will write explanations for the key tasks.

We will explain to the user where to start

The user clicks on the “Add new” button. The new page editing window and the following prompt appear.

We will teach you how to fill out forms correctly

Let's pay attention to important functions

Forming an understanding of working with content

Let's explain special terms

Don't require users to read technical documentation. The tooltip in the screenshot explains the meaning of the new terms. It contains only a few sentences, does not overlap system elements, and is compatible with the interface design.

Once again about the benefits

The value of hints for users is obvious - those who previously needed help master the service or application on their own.

Developers of applications or services will save on the preparation and publication of technical documentation and reference materials. Hints will reduce the load on the technical support service.

Owners of online stores who place tips, for example, on the checkout page, will get rid of some “abandoned carts” and increase conversion and store income.

Study user reactions to the product, create understandable and available instructions. This will reduce losses potential clients and will reduce the cost of attracting them.

This is a translation of an article previously published in the American magazine for Internet entrepreneurs sandhill.com.

Especially for the online publication “ProGrably”, the material has been significantly expanded, mainly by including information on aspects of UX design when developing a web product.