Rules of good form in the preparation of technical documentation

Introduction

IT companies did not immediately come to the conclusion that they need a technical writer, and they don’t think about normative control at all until a bunch of comments come from the customer.

Companies write a lot of documentation, for which not only technical writers are responsible, but also analysts, and project managers, and technical specialists. It is important to understand that you cannot use a technical writer as a designer, it is inappropriate for the company’s costs. You can present information in different ways and high-quality content is not always the key point. The “comfort” of information perception is important and may depend on the way the information is presented, the data is visualized on the sheet.

Standard control – at first glance, an echo from the Soviet Union or something related to state customers. But normative control (hereinafter referred to as NC) is the hygiene of the document.

The NC includes not only the rules of the Russian language (syntax/spelling), but also requirements in common with GOST.

In this article, I will describe the primitive documentation requirements that our team encountered when interacting with a commercial customer when submitting text documents in terms of design.

Document file naming requirements

The document file naming structure is as follows:

XXXX_YYYYY_V._._.YYYY.MM.DD, Where:

XXXX – code according to the list of documents;

YYYYY – document name (for example, User Manual);

V._._. – version of the document;

YYYY.MM.DD – file editing date.

The cipher may contain:

– Code of the All-Russian classifier of enterprises and organizations;

— OKP Classifier Code 2;

— Code adopted by the internal policy of the company.

The name of the document may consist of:

— Document code in accordance with GOST 34.201;

– Document code or letter designation adopted by the internal policy of the company.

Title page

Title – the face of the document, the first thing the user sees when he takes the document to work.

To arrange the blocks on the title page, I like to use a table with hidden lines. The location of the blocks to fill on the title page is shown in the figure below.

Pagination

The document is numbered from the second sheet, on which the table of contents is most often located. If approval / signature sheets are inserted after the title page, they are not numbered, and the numbering of the table of contents also starts from the second number.

Headers and footers in the document can be filled both from above and from below, if a frame is not used in the document (according to GOST 2-105). It is advisable to indicate the project name / document name / document code.

If certain margin sizes are used to design the document, then it is worth considering that the header and footer should not go beyond these fields. To determine this condition in MS Word, the “Grid” mode is used.

Table of contents

For readability and perception of information, I indent the first, second and third levels of the table of contents. If we select subsequent levels, then we will get an endless staircase, and eventually there will be no space left on the sheet.

Heading design

Headings of sections, subsections and applications are printed with a capital letter without a dot at the end, in bold.

Word hyphenation in headings is not allowed.

Section headings (of the first level) are numbered in Arabic numerals with a dot, for example:

The headings of subsections (of the second and subsequent levels) are numbered with Arabic numerals separated by a dot, and without a dot after the number, for example:

The heading of the section/subsection and the text of the presentation should be located on one page. To comply with this, in the “Paragraph” menu of the heading style, in the “Position on the page” tab, check the “do not tear from the next” field.

Main text

There is a lot of information on the Internet on the use of style for the main text, I will not dwell on it.

The main requirements for writing the text will be described below.

In the text of the document it is not allowed to use:

– turns of colloquial speech, technicalisms, professionalisms;

– for the same concept, various scientific and technical terms that are close in meaning, as well as foreign words and terms in the presence of equivalent words and terms in the Russian language;

− arbitrary word formations;

– abbreviations of words, except for those established by the rules of the Russian language and the corresponding section of the document.

The document does not use word wrap.

The body of the document uses:

− letters “Ё”, “ё” without dots, including in proper names;

− quotation marks from the Russian keyboard layout.

Not allowed:

– transfer to the next line (page) only the number of the structural element (figure, table, section, application, etc.);

– to spread on different lines or in different directions the columns of the table the form of ownership (JSC, LLC, etc.) and the name of the organization, as well as the initials and surname;

– separate the unit of magnitude from the numerical value into different lines;

− separate the sign of the number from the number on different lines.

In this case, it is recommended to use a non-breaking space (shortcut Shift+Ctrl+Space).

The text of the document should avoid:

− double spaces;

− empty paragraphs;

– spacing into different lines of parts of compound words written with a hyphen.

It is not allowed to use extra paragraphs for text indentation, double or more spaces.

The text of the document should contain links to all tables, figures, and applications contained in it.

When referring to multiple elements, the following wording is used:

“…given in tables 1–4”, “…in annexes 1–3”, “…as shown in figures 1 and 2”, “…in figures 1–4”, and also as shown in the figure below.

Design of drawings

Any graphic material (drawing, diagram, diagram, drawing, etc.) is designated in the document by the word “drawing”. Figures are numbered through the text of the document, including applications.

Figures are placed directly after the text in which they are mentioned for the first time, or on the next page, and, if necessary, in a separate appendix. Transfer to the next line (page) only the figure number is not allowed. The reference to the figure should be placed at the end of the sentence.

To indicate the sequence of steps described in the text, Arabic numerals enclosed in square brackets are added to the figure reference. In the figure, the same steps are indicated by numbers, if necessary, the desired area is highlighted with a colored frame. An example of the design of links to the steps described in the text is shown in the figure below.

Figures in the text should be framed in the form of a solid black line.

When used in block diagrams, it is necessary to provide explanatory data for the elements of the block diagram (legend).

The name of the figure includes the word “Figure”, a serial number, after which a period is put down. Further, through a space, with a capital letter indicate the thematic name. For the name of the picture, use the height of the font of the main text.

Table design

Tables are numbered in Arabic numerals through numbering throughout the entire document, including annexes. All tables of the document should be referenced in the text of the document, with the reference the word “table” should be written, indicating its number.

Tables are placed directly after the text in which it is mentioned for the first time, or on the next page, and, if necessary, in a separate appendix.

For a paragraph of text after the table, add a “Before” spacing.

For a header row, enable “repeat as header on every page” if the table spans multiple sheets.

Application design

Applications are placed after the main text of the document. Each application starts on a new page. Applications are numbered in Arabic numerals in the order they are mentioned in the text and arranged in ascending order of numbers.

Appendices have a common pagination with the main text of the document.