How to write user instructions correctly. How to make the service more understandable
guidelines for ESPD and IEEE Std 1063-2001, taking into account the “Kagarlitsky manifesto”. It is shown that the generalized structure of the user manual, compiled in accordance with the requirements of the “outdated” GOST 19th system, significantly exceeds the structure of the manual recommended by the ultra-modern IEEE Std 1063-2001. Revision dated June 20, 2018.
How to write a user manual? Part I - generalized structure of the user manual according to GOST 19th system and its comparative analysis with the recommendations of IEEE Std 1063-2001
Created 02/11/2005 11:14:22
When hope dies, despair comes.
Wise Latin proverb
How to write a manual? Create a tree-like user manual and fill in its sections. And all the love.
Where can I find the section structure of the user manual? With the manuals on (operating manual for) and on (), everything is more or less clear. But the document “User’s Guide” of the program itself is not listed as a class in GOSTs of the 19th system.
What content should I fill the sections of the user manual with? What should I do? The main thing is not to despair.
Goals and objectives of the article
As always, try to make life easier for the program user manual.
- analyze existing and development ones, identify the advantages and disadvantages of each document separately;
- derive a certain generalized structure of the user manual according to GOST 19th system from the existing set of operational program documents;
- compare it with the structure recommended by IEEE Std 1063-2001;
- and all other tasks moved to the 2nd part of the article...
Note from 07/10/2014 - In February 2005, perhaps not even a comparative analysis was carried out, but rather comparative tests, which showed the undeniable superiority of the GOST 19th system of standards over the bourgeois ones and the almost complete inconsistency of the latter.
Questions your user manual should answer
Give your child an electronic toy that is unfamiliar to him. The list of questions will be something like this (if it doesn’t break right away):
- what is this;
- and what can they do;
- and what they should not do (for especially gifted people);
- and what is needed for it to work;
- and what is inside him (in children prone to deep things);
- and how to configure it so that it works the way I want;
- and how to check whether it works or not;
- what and where to press;
- what else can it do?
- what does it say if you press something wrong?
The sequence of questions can be very diverse. And the document called “User Guide” should provide answers to all the questions posed. It's simple. The devil is not as scary as he is painted.
User's Guide: Four Sources and Four Components
We have:
- Kagarlitsky's "metaguide";
- cutting-edge IEEE Std 1063-2001, “IEEE Standard for Software User Documentation”;
- classic domestic GOSTs of the 19th system, which includes the following documents of a “descriptive” nature:
The last four from the list are operational program documents.
Perhaps there are other documents, but the author, having thoroughly rummaged through the RuNet dump, has not yet been able to obtain anything more suitable. Yandex has discovered in its depths another page called “How to make a good user manual,” the author of which calls himself an American b Chinese style (like John P. Morgan). The two-page “manual” was immediately thrown into the trash with cheers.
Manifesto of Kagarlitsky
Kagarlitsky's metaguide seemed promising. Only the author of this article did not understand that there is a “metaguide”, so he allowed himself to impudently call the metaguide a “manifesto”. And I did not sin against the truth (but this was revealed later - below).
(quotes from Kagarlitsky’s manifesto)
We sought to combine into a single system the entire set of standard requirements that should, from our point of view, be presented to technical documentation: manuals, reference books, etc. In doing so, we were based on standards (!!!)GOST , Microsoft standards, the experience of our employees and other developers of technical documentation.
The beginning is encouraging.
The technical documentation includes two core parts, which we will call, respectively, the user manual and the user reference book, or briefly: the manual and the reference book (by analogy with the English phrases User's Guide and User's Reference). They can be issued in the form of separate documents (for large software products), or, on the contrary, they can exist in an integrated form. There may not even be a clear boundary between them: a single text can combine the features of a manual and the features of a reference book.
The manual and reference book are not so much parts of documentation, but rather, they embody two approaches to describing a software product.
It's true enough, but the boys are starting to get nervous. Leadership is not a concept, it exists.
Our task is not so much to tell you what the documentation looks like, but to give specific recommendations for its development . Everyone knows what problems arise in the process of writing a large coherent text - how to get started, With where to start, how to arrange the material . This approach encourages us to see in the norms we proclaim chaotic their list, but a hierarchical system ...
A star named Nadezhda shone in the sky - now dear Mr. Kagarlitsky will give us, the dispossessed, a comprehensive hierarchical structure user manuals of all times and peoples. Well?!
Before starting to develop documentation as such, it is necessary to outline and plan the general logic of presentation. It may seem that the genre of technical documentation is extremely simple: after all, its task is “only” to inform the user of some information about the product. However, if you proceed from this in your work, you will create samples of documentation that are completely unsuitable or barely suitable for practical use, - even if everything necessary information will be kept there. Your task is to guide the user through the pass, that is, to find a place in the mountain range that, even if with difficulty, is still passable for your “ward.”
It's a pity... And so it all started well. From "standards" GOST" - "standards" - we will forgive Mr. Kagarlitsky for the tautology. But the solution to the first problem posed by the author of this article is not in the seventy-two-page manifesto (Arial 12pt). Dear author of the manifesto, only put we have a task . Well, there is no prophet in his own country. Maybe there is a prophet in the bourgeois fatherland?
User's Guide to IEEE Std 1063-2001 "IEEE Standard for Software User Documentation"
The foreign “prophetic” document IEEE Std 1063-2001 (IEEE in common parlance - “ay-yay-yay”) in subsection 1.2 (Puprose) contains the following line:
This revision provides requirements for the structure, information content, and format of both printed and electronic documentation.
In the author’s understanding, the purpose (intent, purpose, design, aspiration) of the IEEE Std 1063-2001 document is to “provide requirements for the structure, information content, (design) of both printed user documentation for software.” Well, that's appropriate. What kind of user manual structure does IEEE Std 1063-2001 propose?
IEEE Std 1063-2001 User Guide Structure
An optional typical user manual structure is contained in the table from the Structure of software user documentation section of IEEE Std 1063-2001:
Identification data (package label/title page) | ||
Table of contents | Yes, in documents of more than eight pages after identification data |
|
List of illustrations | ||
Concept of operations | ||
Yes (instructional mode) |
||
Yes (reference mode) |
||
Yes, if documentation contains unfamiliar terms |
||
Related information sources | ||
Navigational features | ||
Yes, if documents of more than 40 pages |
||
Search capability | Yes, in electronic documents |
For purposes of this standard, the following non-mandatory nomenclature is used for the structural parts of software user documentation. A printed document is structured into logical units called chapters, subdivided into topics, which may be subdivided into subtopics, and printed on physical units called pages.
Great. IEEE Std 1063-2001 suggests “taking everything and dividing it up” - dividing the sections of the manual into chapters, topics, subtopics, etc. And happiness will come to everyone.
The highlighted sections are of practical interest (within the scope of the article's objectives). Let's see how to split the sections of the user manual into smaller structural units and what content is supposed to be filled in these structural units.
Introduction
What information must be included in the Introduction section according to IEEE Std 1063-2001? Here's what
The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment.
Well, that's great. The structure of the Introduction subsections is starting to take shape.
Information for use of the documentation
The documentation shall include information on how it is to be used (for example, help on help), and an explanation of the notation (a description of formats and conventions - see 5.8). At least one document in a document set shall identify all documents in the set by title and intended use, including recommendations on which members of the audience should consult which sections of the documentation. In document sets comprising many volumes or products, this information may be provided in a separate "road map" or guide to the document set. Documentation may include identification and discussion of notable changes from the previous version of the document set and the software.
A very useful section (in the development of the user manual). Leadership Guide.
Concept of operations
Documentation shall explain the conceptual background for use of the software, using such methods as a visual or verbal overview of the process or workflow; or the theory, rationale, algorithms, or general concept of operation. Explanations of the concept of operation should be adapted to the expected familiarity of the users with any specialized terminology for user tasks and software functions. Documentation shall relate each documented function to the overall process or tasks. Conceptual information may be presented in one section or immediately preceding each applicable procedure.
Conceptual information is certainly important.
Procedures
Task-oriented instructional mode documentation shall include instructions for routine activities that are applied to several functions:
Software installation and de-installation, if performed by the user
Orientation to use of the features of the graphical user interface (see 5.6)
Access, or log-on and sign-off the software
Navigation through the software to access and to exit from functions
Data operations (enter, save, read, print, update, and delete)
Methods of canceling, interrupting, and restarting operations
These common procedures should be presented once to avoid redundancy when they are used in more complex functions.
And the competition began. Well done, bourgeois!
Information on software commands
Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax. Documentation may be provided on the development and maintenance of macros and scripts. Reference mode documentation shall contain a reference listing of all reserved words or commands. Examples should illustrate the use of commands. Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated.
Error messages and problem resolution
Documentation should address all known problems in using the software in sufficient detail such that the users can either recover from the problems themselves or clearly report the problem to technical support personnel. Reference mode documentation shall include each error message with an identification of the problem, probable cause, and corrective actions that the user should take. A quick reference card may address error messages by referring the user to more detailed reference documentation. The documentation on resolving problems shall also include contact information for reporting problems with software or its documentation and suggesting improvements.
Conclusions according to IEEE Std 1063-2001
But the happiness turned out to be incomplete... The structure of the sections of the first level of the manual is clearly shown in the table. And then - “my dear, good one, guess for yourself” (“guess it yourself”). IEEE Std 1063-2001, of course, “provides requirements for the structure”, but does not offer explicit structures user manuals up to the fourth nesting level recommended by GOST 2.105.
Recommendations like “Documentation shall explain...”, “Examples should illustrate...”, “Documentation shall describe...” and the like are certainly time-tested. The user manual must explain, illustrate, and describe - without any doubt. But all this is clear to a goat, and is spelled out in GOSTs of the 19th system.
So, it is unlikely to develop user manuals based solely on the recommendations of IEEE Std 1063-2001. There are at least two reasons:
- the lack of a clearly regulated user manual structure in IEEE Std 1063-2001;
- “superficiality” of IEEE Std 1063-2001, lack of “breadth of coverage” and “depth of elaboration”.
The absence of a clearly regulated structure of the user manual will make it possible TREAT, see at least. The poor developer will be forced, at the direction of the customer, to swap sections of the user manual day after day (the guaranteed minimum, obtained by experience).
The lack of a clearly regulated structure turns into chaos as soon as the level of nesting of headings is reduced to the second or third. The user will simply throw such a guide far away and call its author a cretin.
According to the author, the recommendations of IEEE Std 1063-2001, developed with the participation of hundreds of foreign specialists, are very, very superficial. The developer, working according to IEEE Std 1063-2001, will not be able to cover the maximum “characteristics” inherent in the program. Many of them are simply not specified in IEEE Std 1063-2001. There is no “breadth of coverage” and “depth of elaboration” characteristic of domestic documents.
The last section of this article contains a table of correspondence between GOST 19 and IEEE Std 1063-2001, which the author of the article began to compile, then abandoned and did not check. Let everyone draw their own conclusions for themselves. And, perhaps, he will correct the author in some way.
User documents according to GOST 19 (ESPD)
Unlike the ultra-modern bourgeois IEEE Std 1063-2001, the ancient, much-maligned domestic standards of the 19th system (Unified System of Program Documentation - ESPD) do not contain lengthy discussions about what and how the user manual should explain, illustrate and describe, but specific requirements for the structure and content of user (operational) documents.
The list of GOSTs 19 of a “descriptive” nature, on the basis of which it is possible, without further ado, to form a clear structure of the sections of each of the “descriptive” documents, is given in the Sources section. The main technique - detailing - is described in detail in the article "". Next - the structures of document sections formed by “detailing” in accordance with GOSTs from the list.
Structure of sections of the program description according to GOST 19.402-78
Structure of application description sections according to GOST 19.502-78
Structure of sections of the system programmer's manual according to GOST 19.503-79
Structure of sections of the programmer's manual according to GOST 19.504-79
Structure of sections of the operator's manual according to GOST 19.505-79
Conclusions according to GOST 19.xxx
Neither, nor, nor, taken individually, can boast of sufficient completeness of structure.
But the structures of “descriptive” documents of GOST 19 have both completely identical (in the text of the names) and similar sections and subsections in the text of the names. Identical sections include, for example, sections “”, which occur in all documents according to. Similar (actually identical) include the subsections “Purpose of the program” and “”.
Why not try to combine all the “descriptive” documents? Combine identical and similar sections of documents, highlight specific sections? Perhaps it will be possible to get rid of the incompleteness of GOST 19.505-79, GOST 19.504-79 and GOST 19.503-79 and obtain a generalized structure of a “descriptive” document and call the document itself a program user manual?
GOST 19.xxx allows “to introduce additional sections or combine individual sections”, as well as “to introduce new ones”. According to GOST 19.101-77 “It is allowed to combine individual species operational documents (with the exception of and). The need is indicated in. The merged document is also assigned the designation of one of the merged documents. The merged documents must contain information that must be included in each merged document [from clause 2.6 of GOST 19.101-77]"
No sooner said than done. Only we will violate GOSTs and create a combined document called “User Guide”.
Generalized structure of the user manual according to GOST 19th system
By merging the structures of “descriptive” documents of GOST 19th system into a single structure, removing “extra” sections of the same name, and merging similar sections, the general structure of the program user manual was formed. The tablet contains “ * » sections that are present in each individual document are marked.
GOST 19.xxx - generalized structure of manual sections | GOST 19.402-78 | GOST 19.502-78 | GOST 19.503-79 | GOST 19.504-79 | GOST 19.505-79 |
Annotation | |||||
Purpose of the document | |||||
General information about the program | |||||
Notation and programs | |||||
In which the program is written | |||||
Information about the purpose of the program | |||||
Information sufficient to understand and | |||||
Program features | |||||
Classes of problems to be solved | |||||
Description of tasks | |||||
Problem solving methods | |||||
Timing characteristics | |||||
Operating mode | |||||
Terms of use of the program | |||||
Information about and ensuring the execution of the program | |||||
Types used when running the program | |||||
Requirements for composition and parameters | |||||
Description of the logical structure | |||||
Programs | |||||
Methods used | |||||
Information about | |||||
Program information | |||||
Information about and | |||||
Input Details | |||||
Output Details | |||||
Format, description and method of output | |||||
Selecting functions | |||||
Explanatory examples | |||||
Description of methods for checking a program | |||||
Test cases | |||||
Run Methods | |||||
Results | |||||
Program Execution | |||||
Starting the program | |||||
Program entry points* | |||||
Control and data transfer methods | |||||
Program Execution | |||||
Format and possible options to perform function 1 | |||||
Additional features | |||||
Texts issued during (setting, checking, executing) the program | |||||
Content Description | |||||
Conclusions on the general structure of the user manual according to GOST 19.xxx
The generalized structure of the user manual according to GOST 19.xxx clearly does not suffer, like IEEE Std 1063-2001, from a lack of breadth of coverage. Excess, as we know, gives rise to quality. Everything that a program can be characterized by is listed. Some subsections may even seem unnecessary, for example, the subsection “Programming languages in which the program is written.”
It would seem, what does the user care in what language the source code of the program was written? On the other hand, maybe “...does anyone need this? This means it is necessary...” After all, when buying a bourgeois TV, you want to get schematic diagram at him. Samsung and Sony also fail. What if the malfunction is trivial and it seems possible to fix it at home, without a trip to the service center?
At the same time, despite all the breadth of coverage, the following are explicitly missing:
- Software installation and de-installation, if performed by the user;
- Orientation to use of the features of the graphical user interface;
- Access, or log-on and sign-off the software;
- Navigation through the software to access and to exit from functions and much more.
The author managed to scatter something in the section Conformity table of GOST 19.xxx and IEEE Std 1063-2001, but there is always not enough time to “wrinkle my mind”; the user manual, as always, should have been ready last week.
The author was too lazy to show the connections between the sections of the generalized user manual and the sections, since the indicated connections are obvious.
Conclusions by sources
So, if the first three problems have been generally solved, the final problem remains unsolved.
The author of the manifesto is more inclined to make recommendations on selection words * and the construction of sentences, IEEE Std 1063-2001, at best, provides requirements for the structure of the user manual, but does not provide much specificity; GOST 19.xxx does not specify procedures for filling out sections of the manual. Maybe organize some kind of mixture of French and Nizhny Novgorod? Use all four sources as four components?
* Nowadays the bourgeoisie is in fashion - the so-called. controlled language . Among representatives of the “enlightened Russian intelligentsia” the most popular is the domestic analogue in the verbal form of the imperative mood - filter bazaar !
A mixture of French and Nizhny Novgorod
Why not? Take the best from GOST 19th system - the generalized structure of the user manual, add to it a few sensible ones from IEEE Std 1063-2001 and dilute it with inexhaustible stylistic culture and resources from Kagarlitsky's manifesto? Give the mixture a slender, strict look, form another one with detailed comments? But what to do if none of the above sources and components separately are capable of providing answers to all the questions posed?
Conformity table GOST 19 and IEEE Std 1063-2001
GOST 19.xxx | IEEE Std 1063-2001 |
Annotation | |
The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment |
|
Purpose of the document | purpose for the document (Introduction) |
Summary of the main body of the document | scope (Introduction) |
General information about the program | |
Designation and name of the program | |
Programming languages in which the program is written | |
Information about the purpose of the program | brief overview of the software purpose (Introduction) |
Information sufficient to understand the functions of the program and its operation | there is no similar subsection |
Program features | |
Classes of problems to be solved | |
Description of tasks | |
Problem solving methods | Documentation shall relate each documented function to the overall process or tasks |
Functions performed by the program | brief overview of the software ... functions (Introduction) |
Description of the main characteristics and features of the program | there is no similar subsection |
Timing characteristics | |
Operating mode | |
Means of monitoring the correct execution and self-healing of the program | |
Limitations on the scope of the program | |
Information about functional restrictions on use | |
Terms of use of the program | If different versions of the software are available for different operating environments, the title page should specify the applicable operating environment(s), including version(s) of hardware, communications, and operating system(s) (4.3. Content of identification data) |
Conditions required for program execution | there is no similar subsection |
Information about the hardware and software that ensures the execution of the program | Documentation for the hardware and software environment (4.11 Information on related information sources) |
Requirements for technical means | there is no similar subsection |
Devices used when running the program | |
RAM capacity | |
Minimum and (or) maximum composition of hardware and software | |
Requirements for the composition and parameters of peripheral devices | |
Software required for the operation of the program | brief overview of the ... operating environment (Introduction) |
Software requirements | there is no similar subsection |
Requirements for other programs | |
Requirements and conditions of an organizational, technical and technological nature | |
Description of the logical structure | |
Program algorithm | algorithms (4.5 Concept of operations) |
Methods used | using such methods as a visual or verbal overview of the process or workflow (4.5 Concept of operations) |
Information about the program structure | there is no similar subsection |
Information about the components of the program | |
Description of the functions of the components | |
Information about connections between components programs | |
Information about connections with other programs | |
Input and Output Details | |
General characteristics of input and output information | there is no similar subsection |
Input Details | |
Nature, organization and preliminary preparation of input data | |
Output Details | |
Nature and organization of output data | |
Format, description and encoding method of output data | |
Description of information encoding | |
Setting up the program | Identification of technical or administrative activities that must be done before starting the task (4.7 Information for procedures and tutorials) |
Description of steps to configure the program | there is no similar subsection |
Adjustment to the composition of technical means | |
Selecting functions | |
Explanatory examples | |
Checking the program | |
Description of ways to check the functionality of the program | there is no similar subsection |
Test cases | Examples should illustrate the use of commands (4.8 Information on software commands) |
Run Methods | there is no similar subsection |
Results | |
Program Execution | |
Software installation and de-installation, if performed by the user (4.6 Information for general use of the software) |
|
Starting the program | there is no similar subsection |
Program entry points* | Access, or log-on and sign-off the software (4.6 Information for general use of the software) |
Methods for transferring control and data parameters | there is no similar subsection |
Program Execution | |
Description of the function performed 1 | A brief overview of the purpose of the procedure and definitions or explanations of necessary concepts not elsewhere included (4.7 Information for procedures and tutorials) |
Format and possible command options for performing function 1 | Navigation through the software to access ... functions (4.6 Information for general use of the software) |
Program responses to commands to execute function 1 | Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated (4.8 Information on software commands) |
Completing program execution | Navigation through the software ... to exit from functions |
Additional features | |
Description of additional functionality programs | there is no similar subsection |
Description of the use of additional program functionality | |
Program messages | Relevant warnings, cautions, and notes that apply to the entire procedure (4.7 Information for procedures and tutorials) |
Texts of messages issued during (setting, checking, executing) the program | there is no similar subsection |
Content Description | |
Description of actions to take in response to these messages |
User manual as software (operational) user documentation
The document "User's Guide" refers to the package of operational documentation. The main purpose of the user manual is to provide the user with the necessary information to independently work with a program or automated system.
Thus, the User's Guide document should answer the following questions: what kind of program is it, what can it do, what is necessary to ensure its correct functioning, and what to do in case of system failure.
Documentation: software/operational/user documentation
Item: program, software component of a complex or system
Audience: users of the program, i.e. persons who use it to solve their own applied problems
Tasks: provide users with the opportunity to fully independently master and apply the program
Guiding standards for creating a User Guide document may include: RD 50-34.698-90 in pp. 3.4. "User Guide", so GOST 19.505-79 “Operator's manual. Requirements for content and design".
The following main sections of the user manual can be distinguished:
Purpose of the system;
Conditions for using the system;
Preparing the system for operation;
Description of operations;
Emergency situations.
Purpose of the system
This section of the User Guide document should contain information about the purpose of the system, its goals and objectives.
Example:
“The corporate intranet portal is designed to improve corporate culture and organize effective interaction between employees.
The main goal of the Port is to create a unified information space for the enterprise and optimize the work of employees by facilitating communications between them and optimizing a number of business processes.”
Conditions for using the system
This section of the User's Guide document should include all those factors that are necessary for the correct operation of the system. There are several subsections here:
Hardware requirements - here you can include requirements for the configuration of the user’s computer, the software necessary for the operation of the System, as well as the availability of additional equipment (printer, scanner, etc.), if necessary;
User qualifications - this subsection should contain requirements for the user’s skills and knowledge ( example: “Users must have the ability to work with operating system Windows");
Preparing the system for operation
This section of the User Guide document should contain step-by-step instructions for launching the application. The stage of preparing the system for operation includes the installation of additional applications (if necessary), identification, authentication, etc.
Description of operations
This is the main section of the User Guide document, which contains step-by-step instructions for the user to perform a particular action.
If the operation of an automated system affects an entire business process, then in the user manual, before describing the operations, it is advisable to provide information about this process, its purpose and participants. Such a solution allows a person to clearly imagine his role in this process and the functions that are implemented for him in the system.
Further in the User's Guide, a description of the functions broken down into individual operations should be provided. It is necessary to highlight subsections that describe the functions of this process and the actions that must be taken to complete them.
Example:
"4.1 Project approval
This process is intended to organize the work of employees involved in the development and approval of the project.
The author of the project creates an entry in the System and attaches a package of necessary documentation, then the project is submitted for approval by management. After reviewing the project, managers can confirm it or send it to the Author for revision.
4.1.1 Creating a project
In order to create a Project, you need to click on the “…” button on the “…” panel and fill in the following fields in the form that appears:
Project name;
Description of the project;
The following fields are filled in automatically:
Project creation date – current date;
The more detailed the actions with the system are described, the fewer questions the user will have. For an easier understanding of all the principles of working with the program, the standards in the User Guide document may include diagrams, tables, and illustrations depicting screen forms.
For large automated systems, it is recommended to create a separate manual for each user category (user, moderator, etc.). If additional user roles are allocated when working with the system, then it is advisable to place a table of the distribution of functions between roles in the User Guide document.
Emergency situations
This section of the User Guide document should contain step by step instructions user actions in case of System failure. If the user has not been subject to special requirements for administering the operating system, etc., then you can limit yourself to the phrase “If the System fails or malfunctions, you must contact the System Administrator.”
Methodology and style of presentation of the user manual
The user manual can be either a quick reference guide to the main functionality of the program or a complete tutorial. Methodology for presenting material in in this case will depend on the scope of the program itself and the customer’s requirements.
Depending on the features of the program and target audience The user's manual in terms of the way the material is presented may 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 major program similar 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, where to direct them, 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 strongly recommended to include a conceptual 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.
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 the use of 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 beginning, leaving for last the most complex details regarding, say, reprogramming capabilities 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 methods of use of the manual; - sections explaining the use of the product on different stages its use, for example, first steps, repair or prevention; - section of frequently asked questions and answers to them; - 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.
Hello again, dear habralyud!
In continuation of my post, I decided to write about the best way to create instructions for users and administrators.
To everyone who is interested, please share.
KISS
The Keep It Simple Stupid principle is well known in programming, but for some reason it is rarely used to write instructions and guidance documents, preferring to spread thoughts along the tree. In 70% of situations, this documentation is necessary only to brush off our cheerful regulators, but at the same time they forget that this documentation will have to be worked with, and not always by technically savvy and knowledgeable people in the field of information security.To begin with, I’ll write a few rules that will help you create a working and convenient document:
1.
Try to separate instructions for users from instructions for administrators and security officers. Moreover, the first should not contain references to the second (they can contain references to each other).
2.
Give step-by-step instructions, like “take it and do it.” That is, the instructions must describe the algorithm of actions of the person to whom it is directed.
3.
Describe each item as a separate action with a mandatory indication of the person responsible and contacts, if necessary.
4.
For greater clarity, you can additionally draw a flowchart of actions in the instructions. This will help the user to clearly understand and evaluate the actions, and it will also be easy for you to explain the algorithm when training.
5.
The psychological point is that the instructions will be poorly followed and work if the algorithm is not explained to users in a clear and accessible manner using examples and examples. That's why - DON'T FORGET ABOUT TRAINING!
Example instructions for users
Below is an example of instructions for creating a user account on a corporate network.Clear screen/clear desk
The specificity of Russian organizations that have been operating since Soviet times and have equally experienced employees is such that, as a rule, their desks are littered with papers. The computer sometimes does not turn off or lock, even when they go home. Recently I personally saw, walking past a municipal enterprise late at night, how a monitor with a Word document open on it was burning behind open blinds in a locked building.Users are sometimes unaware of possible unintentional information leaks. Even if it is not confidential, it may be for internal use only. But this gives an understanding that this organization does not care about its security and can do this with confidential information. It is also possible that there will be information that is not yet classified as closed, but already exists in the internal circulation of the organization.
A good example of best practice here is the clear desk and clear screen policies. They can be described in the same way as I gave an example earlier, but it will look a little stupid, since the actions there are very simple. It's better to just make it a set of rules: 
P.S. The post contains screenshots of actually implemented and working instructions and policies. All similarities with existing organizations are purely coincidental. All department and bureau names have been changed.
Eh... this is “life”!
I was convinced by personal example that writing user manuals is not such an easy task... Especially if you don’t know software product 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 (it seems like something from accounting, which I’m not very 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 thing 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 end user(it is best to describe the swing in detail!), it is necessary to determine the degree 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 then write for each functional module separate manuals. 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 point 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 a description, see the website section).
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 a brief description of 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 it is described short algorithm working with a module/submodule (downloading, viewing, adding, editing, deleting, generating reports, etc.), after which a more detailed description of all functionality and all available fields is provided.. 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 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 beautiful 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’s 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