Experience in using ESP. Registration of software documentation according to the espd, espd Documentation for GOST software

Date of introduction from 01.01.80

This standard specifies the types of programs and program documents For computers, complexes and systems, regardless of their purpose and scope.

The standard fully complies with ST SEV 1626-79.

1. TYPES OF PROGRAMS

1.1. The program (according to GOST 19781-90) can be identified and used independently and (or) as part of other programs.

1.2. Programs are divided into types shown in table. 1

Table 1

1.3. The documentation developed for the program can be used for the implementation and transfer of the program on storage media, as well as for the manufacture of a software product.

1.2,1.3.

2. TYPES OF PROGRAM DOCUMENTS

2.1. Software documents include documents containing information necessary for the development, production, maintenance and operation of programs.

2.2. Types of program documents and their contents are given in table. 2.

table 2

Type of program document	Contents of the policy document
Specification	Composition of the program and its documentation
	List of enterprises that store original program documents
Program text	Recording the program with the necessary comments
Program description	Information about the logical structure and operation of the program
	Requirements to be verified when testing a program, as well as the procedure and methods for their control
Technical task	Purpose and scope of the program, technical, techno-economic and special requirements for the program, necessary stages and terms of development, types of tests
Explanatory note	Algorithm diagram, general description of the algorithm and (or) operation of the program, as well as justification of the adopted technical and technical-economic decisions
Operational documents	Information to ensure the functioning and operation of the program

(Changed edition, Amendment No. 1).

2.3. Types of operational documents and their contents are given in Table 3.

Table 3

Type of operational document	Contents of the operational document
	List of operational documents for the program
Form	Main characteristics of the program, completeness and information about the operation of the program
Description of application	Information about the purpose of the program, scope of application, methods used, class of problems to be solved, restrictions for use, minimum configuration of hardware
	Information for testing, ensuring operation and customizing the program for the conditions of a specific application
Programmer's Guide	Information for using the program
Operator's manual	Information to ensure the procedure for communication between the operator and the computer system during program execution
Language description	Description of the syntax and semantics of the language
	Information for the use of test and diagnostic programs when servicing technical equipment

(Changed edition, Amendment No. 1).

2.4. Depending on the method of implementation and the nature of application, program documents are divided into original, duplicate and copy (GOST 2.102-68), intended for the development, maintenance and operation of the program.

2.5. The types of program documents developed at different stages and their codes are given in the click table. 4.

Table 4

Document type code	Document type	Development stages
		Preliminary design	Technical project	Working draft
				component	complex
-	Specification	-	-
05	List of original holders	-	-	-
12	Program text	-	-
13	Program description	-	-
20	List of operational documents	-	-
30	Form	-	-
31	Description of application	-	-
32	Management system programmer	-	-
33	Programmer's Guide	-	-
34	Operator's manual	-	-
35	Language description	-	-
46	Maintenance Manual	-	-
51	Test program and methodology	-	-
81	Explanatory note			-	-
90-99	Other documents

Legend:
- the document is mandatory;
- the document is mandatory for components that have independent use;
- the need to draw up a document is determined at the stage of development and approval terms of reference;
- - the document is not drawn up.

2.2-2.5. (Changed edition, Amendment No. 1).

2.6. It is allowed to combine certain types of operational documents (with the exception of the list of operational documents and the form). The need to combine these documents is indicated in the technical specifications. The merged document is assigned the name and designation of one of the merged documents.

Merged documents must specify the information that must be included in each document being merged.

2.7. At the stage of development and approval of the technical specifications, the need to draw up technical specifications containing requirements for the production, control and acceptance of the program is determined.

Technical specifications are developed at the “Detailed Design” stage.

2.8. The need to draw up technical specifications for components not intended for independent use, and complexes included in other complexes, is determined by agreement with the customer.

(Introduced additionally, Amendment No. 1).

Reissue (November 1987) with Change No. 1, approved in June 1981 (IUS 9-81)

Computer programs are designed in accordance with the requirements of the Unified System program documentation(ESPD). ESPD is a set of GOSTs that establish the rules for the design, content, and structure of program documents.
This how-to contains excerpts from the ESPD. Complete information can be obtained directly from GOSTs.

Brief program design algorithm

Briefly, the program design algorithm and types of program documents are shown in the figure. The registration process is described in more detail below.

Preparation of a program document

Program document - a document containing information necessary for the development, production, maintenance and operation of programs.

Each individual program document is drawn up in accordance with (common to all ESPD documents) the requirements of GOST 19.101-77, GOST 19.103-77, GOST 19.104-78, GOST 19.105-78, GOST 19.106-78, GOST 19.604-78 (a more detailed description of these GOSTs follows below) and GOST for a specific program document.

General requirements for program documents. GOST 19.105 - 78

Requirements for printed program documents. GOST 19.106 - 78

GOST 19.106-78 establishes the rules for the execution of program documents for the printed method of execution.

It is important to note that this GOST does not apply to the program document “Program Text”.

Materials of the program document must be in the following sequence:

• Title part:
  • approval sheet (not included in the total number of sheets of the document);
  • title page (first page of the document);
• Information part:
  • annotation;
  • table of contents;
• Main part:
  • text of the document (with pictures, tables, etc.);
  • applications;
  • list of terms, list of abbreviations, list of figures, list of tables, subject index, list of reference documents;
  • change logging part:
  • change registration sheet.

The annotation indicates the edition of the program and briefly outlines the purpose and content of the document. If the document consists of several parts, the total number of parts is indicated in the annotation. The contents of the document are placed on a separate (numbered) page (pages) after the annotation, provided with the heading “CONTENTS”, not numbered as a section and included in the total number of pages of the document.

Text formatting:

• The program document is executed on one side of the sheet, at two intervals; allowed at one or one and a half intervals.
• The abstract is placed on a separate (numbered) page with the heading “ABSTRACT” and is not numbered as a section.
• Section headings are written in capital letters and placed symmetrically relative to the right and left borders of the text.
• Subsection headings are written from the paragraph in lowercase letters (except for the first capital).
• Hyphenation of words in headings is not allowed. There is no period at the end of the title.
• The distance between the heading and the following text, as well as between section and subsection headings, should be equal to:
  • when executing a document by typewriting - two intervals.
• For sections and subsections, the text of which is written on the same page with the text of the previous section, the distance between the last line of text and the subsequent heading should be equal to:
  • when executing a document using a typewritten method - three typewritten intervals.
• Sections, subsections, paragraphs and subparagraphs should be numbered in Arabic numerals with a dot.
• Within the section there must be continuous numbering for all subsections, items and sub-items included in this section.
• The numbering of subsections includes the section number and serial number subsection included in this section, separated by a dot (2.1; 3.1, etc.).
• If there are sections and subsections, the serial number of the clause and subclause (3.1.1, 3.1.1.1, etc.) is added to the subsection number after the dot.
• The text of the document should be short, clear, excluding the possibility of misinterpretation.
• Terms and definitions must be uniform and comply with established standards, and in their absence - generally accepted in the scientific and technical literature, and be given in the list of terms.
• Necessary explanations to the text of the document can be provided in footnotes.
• A footnote is indicated by a number with a bracket placed at the level of the top edge of the font, for example: “printing device2)...” or “paper5)”.
• If the footnote refers to a single word, the footnote sign is placed directly next to this word, but if to the sentence as a whole, then at the end of the sentence. The footnote text is placed at the end of the page and separated from the main text by a 3 cm long line drawn on the left side of the page.
• Illustrations, if there is more than one of them in a given document, are numbered in Arabic numerals throughout the entire document.
• Formulas in a document, if there is more than one of them, are numbered in Arabic numerals; the number is placed on the right side of the page, in brackets at the formula level.
• The meaning of the symbols and numerical coefficients included in the formula must be given directly below the formula. The meaning of each character is printed on a new line in the order in which they are given in the formula. The first line of the transcript should begin with the word “where”, without a colon after it.
• In program documents, references to standards (except for enterprise standards), technical specifications and other documents (for example, documents of State Supervision bodies, rules and regulations of the USSR State Construction Committee) are allowed. When referring to standards and technical specifications, their designation is indicated.
• Reference should be made to the document as a whole or to its sections (indicating the designation and name of the document, number and name of the section or appendix). When repeating references to a section or application, only the number is indicated.
• Notes to the text and tables indicate only reference and explanatory data.
• One note is not numbered. After the word “Note” put a period.
• Several notes should be numbered in order using Arabic numerals with a dot. After the word “Note” put a colon.
• Abbreviations of words in the text and inscriptions under illustrations are not allowed.
• Illustrated material, tables or supporting text may be presented in the form of appendices.
• Every application must start with new page indicating the word “APPLICATION” in the upper right corner and have a thematic heading, which is written symmetrically to the text in capital letters.

GOST contains a sample sheet that indicates the fields, places for page numbering and code.

Name:

Unified system of program documentation.

Valid

Date of introduction:

Cancellation date:

Replaced by:

Text GOST 19.101-77 Unified system of program documentation. Types of programs and program documents

GOST 19.101-77

INTERSTATE STANDARD

UNIFIED SOFTWARE DOCUMENTATION SYSTEM

TYPES OF PROGRAMS AND PROGRAM DOCUMENTS

Official publication

Standardinform

UDC 002:651.7/.78:006.354

Group T55

INTERSTATE STANDARD

Unified system of program documentation

TYPES OF PROGRAMS AND PROGRAM DOCUMENTS

Unified system for program documentation.

Types of programs and program documents

By Resolution of the State Committee of Standards of the Council of Ministers of the USSR dated May 20, 1977 No. 1268, the introduction date was set

This standard establishes the types of programs and program documents for computers, complexes and systems, regardless of their purpose and scope.

The standard fully complies with ST SEV 1626-79.

(Changed edition, Amendment No. 1).

1. TYPES OF PROGRAMS

1.1. The program (according to GOST 19781-90) can be identified and used independently and (or) as part of other programs.

1.2. Programs are divided into types shown in table. 1.

1.3. The documentation developed for the program can be used for the implementation and transfer of the program on storage media, as well as for the manufacture of a software product.

1.2, 1.3. (Changed edition, Amendment No. 1).

2. TYPES OF PROGRAM DOCUMENTS

2.1. Software documents include documents containing information necessary for the development, production, maintenance and operation of programs.

2.2. Types of program documents and their contents are given in table. 2.

Official publication ★

Reproduction is prohibited

) Standards Publishing House, 1977 © STANDARDINFORM, 2010

Edition (January 2010) with Amendment No. 1, approved in June 1981 (IUS 9-81).

table 2

Type of program document
Specification	Composition of the program and its documentation
List of holders of authentic	List of enterprises that store original programs -
	new documents
Program text	Recording the program with the necessary comments
Program description	Information about the logical structure and operation of the program
Test program and methodology	Requirements to be verified when testing the program, as well as
	procedure and methods of their control
Technical task	Purpose and scope of the program, technical, techno-economic and special requirements for the program, necessary stages and terms of development, types of tests
Explanatory note	Algorithm diagram, general description of the algorithm and (or) operation of the program, as well as justification of the adopted technical and technical-economic decisions
Operational documents	Information to ensure the functioning and operation of the program

2.3. Types of operational documents and their contents are given in table. 3.

Table 3

operational document

List of operational documents Form

Description of application

Programmer's Guide Operator's Guide

Language Description Service Manual

List of operational documents for the program

Main characteristics of the program, completeness and information about the operation of the program

Information about the purpose of the program, scope of application, methods used, class of problems to be solved, restrictions for use, minimum configuration of hardware

Information for testing, ensuring operation and customizing the program for the conditions of a specific application

Information for using the program

Information to ensure the procedure for communication between the operator and the computer system during program execution

Description of the syntax and semantics of the language

Information for the use of test and diagnostic programs when servicing technical equipment

2.4. Depending on the method of implementation and the nature of application, program documents are divided into original, duplicate and copy (GOST 2.102-68), intended for the development, maintenance and operation of the program.

2.5. The types of program documents developed at different stages and their codes are given in Table. 4.

Table 4

Document type code	Document type	Development stages
		Sketchy	Technical	Working draft
				component	complex
	Specification
	List of holders of authentic
	Program text
	Program description
	Operating sheet
	documents
	Form

Continuation of table 4

Document type code			Development stages
	Document type	Sketchy	Technical	Working draft
				component	complex
	Description of application
	System Programmer's Guide
	Programmer's Guide
	Operator's manual
	Language description
	Maintenance Manual
	Test program and methodology
	Explanatory note
	Other documents

Legend:

The document is mandatory;

C - a mandatory document for components that have independent use;

O - the need to draw up a document is determined at the stage of development and approval of the technical specifications;

The document is not drawn up.

2.2-2.5. (Changed edition, Amendment No. 1).

2.6. It is allowed to combine certain types of operational documents (with the exception of the list of operational documents and the form). The need to combine these documents is indicated in the technical specifications. The merged document is assigned the name and designation of one of the merged documents.

Merged documents must specify the information that must be included in each document being merged.

2.7. At the stage of development and approval of the technical specifications, the need to draw up technical specifications containing requirements for the production, control and acceptance of the program is determined.

Technical specifications are developed at the “Detailed Design” stage.

2.8. The need to draw up technical specifications for components not intended for independent use, and complexes included in other complexes, is determined by agreement with the customer.

(Introduced additionally, Amendment No. 1).

• GOST 19.001-77 Unified system of program documentation. General provisions
• GOST 19.005-85 Unified system of program documentation. P-schemes of algorithms and programs. Conventional graphic designations and execution rules
• GOST 19.101-77 Unified system of program documentation. Types of programs and program documents
• GOST 19.102-77 Unified system of program documentation. Development stages
• GOST 19.103-77 Unified system of program documentation. Designations of programs and program documents
• GOST 19.104-78 Unified system of program documentation. Basic inscriptions
• GOST 19.105-78 Unified system of program documentation. General requirements for program documents
• GOST 19.106-78 Unified system of program documentation. Requirements for printed program documents
• GOST 19.201-78 Unified system of program documentation. Technical task. Requirements for content and design
• GOST 19.202-78 Unified system of program documentation. Specification. Requirements for content and design
• GOST 19.301-79 Unified system of program documentation. Test program and methodology. Requirements for content and design
• GOST 19.401-78 Unified system of program documentation. Program text. Requirements for content and design
• GOST 19.402-78 Unified system of program documentation. Program description
• GOST 19.403-79 Unified system of program documentation. List of original holders
• GOST 19.404-79 Unified system of program documentation. Explanatory note. Requirements for content and design
• GOST 19.501-78 Unified system of program documentation. Form. Requirements for content and design
• GOST 19.502-78 Unified system of program documentation. Description of application. Requirements for content and design
• GOST 19.503-79 Unified system of program documentation. System Programmer's Guide. Requirements for content and design
• GOST 19.504-79 Unified system of program documentation. Programmer's Guide. Requirements for content and design
• GOST 19.505-79 Unified system of program documentation. Operator's manual. Requirements for content and design
• GOST 19.506-79 Unified system of program documentation. Description of the language. Requirements for content and design
• GOST 19.507-79 Unified system of program documentation. List of operational documents
• GOST 19.508-79 Unified system of program documentation. Maintenance Manual. Requirements for content and design
• GOST 19.601-78 Unified system of program documentation. General rules for duplication, accounting and storage
• GOST 19.602-78 Unified system of program documentation. Rules for duplication, accounting and storage of printed program documents
• GOST 19.603-78 Unified system of program documentation. General rules for making changes
• GOST 19.604-78 Unified system of program documentation. Rules for making changes to printed program documents
• GOST 28195-89 Assessment of the quality of software. General provisions
• GOST 34.601-90 Information technology. Set of standards for automated systems. Automated systems. Stages of creation
• GOST 34.602-89 Information technology. Set of standards for automated systems. Terms of reference for the creation of an automated system
• GOST R 56447-2015 Gas, gas condensate, oil and gas and oil and gas condensate fields. Software for processing and interpreting seismic data. Basic functional and technical requirements
• GOST R 56448-2015 Gas, gas condensate, oil and gas and oil and gas condensate fields. Software for geological modeling of deposits. Basic functional and technical requirements
• GOST R 56450-2015 Gas, gas condensate, oil and gas and oil and gas condensate fields. Software for hydrodynamic modeling of hydrocarbon collection and treatment systems. Basic functional and technical requirements
• GOST R 55711-2013 Complex of technical means of automated adaptive HF (HF) duplex radio communication. Work algorithms
• GOST R 56566-2015 Information technologies. Process evaluation. Part 9. Target Process Profiles
• GOST R 55692-2013 Electronic modules. Methods for compiling and debugging test programs for automated control
• GOST R 56449-2015 Gas, gas condensate, oil and gas and oil and gas condensate fields. Software for hydrodynamic modeling of fields. Basic functional and technical requirements
• GOST R 56413-2015 Information technologies. European ICT Job Profiles
• GOST R ISO/IEC 15026-1-2016 System and software engineering. Warranty of systems and software. Part 1. Concepts and vocabulary
• GOST R ISO/IEC 15026-4-2016 System and software engineering. Warranty of systems and software. Part 4. Life cycle guarantees
• GOST R 56920-2016 System and software engineering. Software testing. Part 1. Concepts and definitions
• GOST R 56921-2016 System and software engineering. Software testing. Part 2: Testing Processes
• GOST R ISO/IEC 26555-2016 System and software engineering. Product Line Technical Management Tools and Techniques
• GOST R ISO/IEC 29155-1-2016 System and software engineering. Structure of comparative analysis of the effectiveness of information technology projects. Part 1. Concepts and definitions
• GOST R 54360-2011 Laboratory information management systems (LIMS). Standard Guide for LIMS Validation
• GOST R 54593-2011 Information technologies. Free software. General provisions
• GOST R ISO/IEC 12207-2010 Information technology. System and software engineering. Software life cycle processes
• GOST R 53798-2010 Standard Guide for Laboratory Information Management Systems (LIMS)
• GOST R ISO/IEC 15504-1-2009 Information technologies. Process evaluation. Part 1: Concept and Vocabulary
• GOST R ISO/IEC 15504-2-2009 Information technology. Process evaluation. Part 2: Conducting the assessment
• GOST R ISO/IEC 15504-3-2009 Information technology. Process evaluation. Part 3: Assessment Guide
• GOST R 57098-2016 System and software engineering. Life cycle management. Process Description Guide
• GOST R 57100-2016 System and software engineering. Description of the architecture
• GOST R 57101-2016 System and software engineering. Life cycle processes. Project management
• GOST R 57102-2016 Information technologies. System and software engineering. Life cycle management. Part 2: Guidance on the application of ISO/IEC 15288
• GOST R 57122-2016 Gas, gas condensate, oil and gas and oil and gas condensate fields. Well construction design software. Basic functional and technical requirements
• GOST R 57193-2016 System and software engineering. Systems life cycle processes
• GOST R ISO/IEC 15504-5-2016 Information technologies. Process evaluation. Part 5: Sample Software Life Cycle Process Assessment Model
• GOST 34009-2016 Means and systems for controlling railway traction rolling stock. Software requirements
• GOST R 57318-2016 Industrial automation systems and integration. Application and management of systems engineering processes
• GOST R ISO/IEC 25001-2017 Information technology. System and software engineering. Systems and Software Quality Requirements and Evaluation (SQuaRE). Planning and management
• GOST R ISO/IEC 33004-2017 Information technology. Process evaluation. Requirements for process reference models, process assessment models and maturity models
• GOST R ISO/IEC 15414-2017 Information technologies. Open distributed processing. Reference model. Enterprise description language
• GOST IEC 60848-2016 GRAFCET specification language for sequential function diagrams
• GOST R ISO/IEC 25051-2017 Information technologies. System and software engineering. Systems and Software Quality Requirements and Evaluation (SQuaRE). Ready-to-use software product (RUSP) quality requirements and testing instructions
• GOST R ISO/IEC 33001-2017 Information technologies. Process evaluation. Concepts and terminology
• GOST R ISO/IEC 33002-2017 Information technologies. Process evaluation. Requirements for conducting a process assessment
• GOST R ISO/IEC 33003-2017 Information technologies. Process evaluation. Requirements for process measurement systems
• GOST R ISO/IEC 33020-2017 Information technologies. Process evaluation. Process measurement system for assessing process capability
• GOST R 57640-2017 Information technologies. Process Reference Model (RPM) for Information Security Management
• GOST R ISO/IEC 30121-2017 Information technologies. Concept for managing risks associated with forensic examination of evidence presented in digital form
• GOST R 58041-2017 Gas, gas condensate, oil and gas and oil and gas condensate fields. A system of software standards for solving problems of prospecting, exploration and development of deposits. Basic provisions and technical requirements
• GOST R 58042-2017 Gas, gas condensate, oil and gas and oil and gas condensate fields. Basic requirements for the initial data of software systems for solving problems of prospecting, exploration and development of fields
• GOST R ISO/IEC 10746-1-2004 Information technology. Open distributed processing. Basic model. Part 1. Basic provisions
• GOST R ISO/IEC 10746-4-2004 Information technology. Open distributed processing. Basic model. Part 4. Architectural semantics
• GOST R ISO/IEC 12119-2000 Information technology. Software packages. Quality requirements and testing
• GOST R ISO/IEC 12207-99 Information technology. Software life cycle processes
• GOST R ISO/IEC 14764-2002 Information technology. Software support

Today we will talk about domestic standards for project documentation. How these standards work in practice, why they are bad and why they are good. When developing documentation for government and serious private customers, we usually have no choice - compliance with standards is included in the requirements for documenting technical specifications. In practice, I have encountered various examples of misunderstanding of the structure of standards, what should be in the documents and why these documents are needed. As a result, the pens of technical writers, analysts and specialists sometimes produce such gems that it is unclear in what state of consciousness they were written. But in fact, everything is quite simple. A search on Habr did not return links to more or less complete material on this topic, so I propose to paint over this annoying gap.

What are documentation standards?

In the 34 series in question, there are only 3 main documentation standards:

The most beloved and popular standard for the development of technical specifications. The only thing you should not forget is that it is tightly connected with other standards of the series and if you have received technical specifications made according to this standard, it is highly advisable to adhere to other standards, even if there are no direct requirements for this. At least in terms of general ideology (about which below)

This is a basic document that provides a complete list of GOST 34 documentation, recommendations for coding documents, which stages of the project the documents belong to (the stages are described in GOST 34.601-90), as well as how they can be combined with each other.

In fact, this standard is a large table with comments. It can be put into Excel for ease of use.

A voluminous standard that describes the content of project documents with varying degrees of detail. The above-mentioned GOST 34.201-89 is used as an index.

There are many questions and interpretations of its provisions regarding the RD 50-34.698-90 standard, which, due to their vagueness, are often understood differently by the customer and the contractor, or even members of the project team. But, unfortunately, we don’t have anything more concrete.

Let us now consider the pros and cons of the standards, traditionally starting with the cons.

Disadvantages of standards

The main disadvantage is obvious to everyone - the standards are old. They contain an outdated idea of ​​the architecture of an automated system. For example:

• two-tier applications, consisting of a client program and a DBMS server (no three or more “tier” applications, no Weblogic or JBoss)
• the structure of the database tables, being described, will give an idea of ​​the logical data model (the fact that there could be some kind of Hibernate between the application and the database seemed like a bad excess then)
• the user interface is single-window (is there anything else? What is a “browser”?)
• There are few reports in the system; they are all paper and printed on a dot-matrix printer.
• The program being developed is focused on solving the “information processing problem,” which has a clear input and output and is highly specialized. Information processing is based on an “algorithm”. Sometimes there are several “algorithms”. (Object-oriented programming was then just taking its first steps and was not seriously considered).
• the database administrator understands what information is in the tables and actively participates in editing system directories (is there really one DBMS server for 50 different applications?)

Accordingly, the standard has artifacts like the following:

5.8. Drawing of the document form (video frame)
The document must contain an image of the form of the document or video frame in accordance with the requirements of state standards of the unified documentation system R 50-77 and the necessary explanations.

The point of the document is that Soviet enterprises used so-called “Printing Areas”, where there were high-speed matrix printers, the drivers for which were often written by the engineers themselves. Therefore, they had to maintain a register of all the documents that needed to be printed to ensure that the documents looked as they should when printed.

“Video frame” is also a document that was displayed on a text display. The displays did not always support the required characters and the required number of horizontal characters and vertical lines (and did not support graphics at all). Therefore, here, too, it was necessary to additionally coordinate the forms of all screen documents.

Now the words “machineogram”, “video frame”, “ADC” no longer tell us anything. I also didn’t find them in use, although I graduated from a specialized institute in the 90s. It was time emergence of Windows 3.1, VGA displays, three-inch floppy disks and the first domestic Internet sites. But these words are in the standard, and the customer sometimes capriciously demands that we provide him with a complete set of documentation in accordance with GOST 34.201-89. Moreover, such formulations in the ToR migrate from one ministry to another and have already become a kind of unspoken template into which the content is hammered.

So the document with the stupid name “Drawing of the document form (video frame)” in the project should and should not be empty.

What's good in the standard

Any standard is good in that it allows the customer and the contractor to speak the same language and provides a guarantee that, at least, the customer will not have any complaints “in form” to the transmitted results.

And the GOST 34 standards are also good because they were compiled by smart people, tested over the years, and they have a clear goal - to describe on paper as fully as possible the complex abstract essence that any automated control system represents.

When you need to competently set a task for Western contractors who have never heard of our GOSTs, you can also rely on these standards, or rather on their content and semantic component. Because, I repeat, the guarantee of completeness of information is worth a lot. No matter how much we flatter ourselves with the high level of our professionalism, we may forget to include elementary things in our requirements, while the same GOST 34.602-89 “remembers” everything. If it is not clear to you what the result of the work of Western contractors should look like, look at the documentation requirements and recommended sections. I assure you, it’s better not to think of it! Most likely, there are Western analogues of our standards, in which everything can be more complete, more modern and better. Unfortunately, I am not familiar with them, since there has not yet been a single case where our GOST standards were not enough.

You can laugh at the fact that the standards creators knew nothing about java or .NET, about HD monitors and the Internet, but I would not advise underestimating the scale of the work they did and its value to our professional community.

How to read and understand documentation standards according to GOST series 34

The standard divides all documents along two axes - time and subject area. If you look at Table 2 in GOST 34.201-89, you can clearly see this division (columns “Creation stage” and “Part of the project”

Stages of creating an automated control system

The stages of creation are defined in GOST 34.601-90. Three of them are relevant to documentation:

• Draft design (ED)
• Technical design (TP)
• Development of working documentation (DD)

Preliminary design follows after the Technical Specifications stage and serves to develop preliminary design solutions.

Technical project describes future system from all angles. Documents at the TP stage should, after reading, leave behind complete clarity in the proposed approaches, methods, architectural and technical solutions. At the next phase it will be too late to describe approaches and justify technical solutions, so phase P is the key to successful delivery of work, since all the variety of requirements of the technical specifications must be reflected in the documents of phase P. At phase P, the system may not exist at all.

Working documentation designed for successful deployment, commissioning and continued operation new system. These are documents containing very specific information that describe physically existing entities, in contrast to the P phase, which describes future splendor.

Parts (sections) of project documentation for the creation of an automated control system

The subject area is divided into “Provisions”. At first it seems that such a division is redundant and unnecessary. But when you start working with this toolkit in practice, the ideology embedded in it gradually becomes clear.

An automated system, as defined by the compilers of GOST, is a combination of hardware, software and communication channels that processes information coming from different sources in accordance with certain algorithms and produces processing results in the form of documents, data structures or control actions. A primitive model of the simplest machine gun.

In order to fully describe this “machine”, the following sections are made (as in drawing):

Software (MS), answering the questions: what logic is hardwired inside the “black box”? Why were these particular algorithms, these particular formulas and these particular coefficients chosen?

Mathematical software knows nothing about processors or databases. This is a separate abstract area, the abode of “spherical horses in a vacuum.” But mathematical software can be very closely related to the subject area, aka Real Life. For example, control algorithms for traffic control systems must be approved by the State Traffic Safety Inspectorate before they are approved by the customer. And then you understand why they are included in a separate book. Because no one in the traffic police is interested in what OS the application server will run on, but what sign and speed limit will pop up on the board in the rain or snow is very interesting. They are responsible for their part and are not going to sign anything else. On the other hand, when they signed, there will be no questions about the technical side of the issue - why they chose those boards or traffic lights and not others. The wisdom of the “ancestors” is precisely manifested in such practical cases.

Information support (IS). Another slice of the system. This time the black box of our system is made transparent and we look at the information circulating in it. Imagine a model of the human circulatory system when all other organs are invisible. Something like this is Information Support. It describes the composition and routes of information flow inside and outside, the logical organization of information in the system, a description of reference books and coding systems (those who made programs for production know how important they are). The main descriptive part falls on the TP stage, but some “rudiments” flow into the RD stage, like the “Database Catalog” document. It is clear that previously it contained exactly what is written in the title. But today, try to create such a document for a complex complex system, when very often the system uses purchased subsystems with their own mysterious information storages. I'm not even saying that this document is not particularly needed now.

Or here is the “Statement of computer storage media”. It is clear that previously it contained numbers of magnetic drums or reels of film. Now what should I put in there?

In short, at the RD phase, Information Support documents represent a rather harmful rudiment, since formally they should exist, but there is nothing special to fill them with.

Software. Everyone's favorite part of project documentation. Yes, if only because it is just one document! And then, everyone understands what needs to be written down there. But I’ll repeat it anyway.

In this document we must tell you how to software the algorithms described in the MO are executed, processing the information described in the IO. That is, there is no need to duplicate information from other sections here. Here the architecture of the system is given, the rationale for the selected software technologies, their description (all sorts of system things: programming languages, frameworks, operating systems, etc.). Also in this document we describe how information processing tools are organized (message queues, storage facilities, Reserve copy, accessibility solutions, all sorts of application pools, etc.). The standard has detailed description the contents of this document, which any specialist will understand.

Technical support (TO). No less beloved part of the project documentation. The rosy picture is only clouded by the abundance of documents that need to be developed. In total, the standard requires the development of 22 documents, of which 9 are at the TC stage.

The fact is that the standard provides a description of all technical support, including computer hardware and networks, engineering systems and even the construction part (if required). And this economy is regulated by a huge number of standards and regulations, coordinated in different organizations, and therefore it is more convenient to split everything into parts and coordinate (edit) in parts. At the same time, the standard allows you to combine some documents with each other, which makes sense if the whole bunch is approved by one person.

Do not forget also that a set of quality standards implies recording and storage of technical documents, and our “books” from the customer may be distributed among different archives, depending on the subject of the description. This is another argument in favor of fragmenting documentation.

Organizational support (OO). Having suppressed the desire, normal for a techie, to skip through this section as quickly as possible, on the contrary, I will consider it in more detail. Since, colleagues, recently there have been some bad trends in projects that require clarification in this section.

At the TP stage, the section contains only one document “ Description of the organizational structure", in which we must tell the customer what he should prepare for in terms of changing the organizational structure. Suddenly you need to organize a new department to operate your system, introduce new positions, etc.

At the RD stage, other, more interesting documents appear, which I would like to consider separately.

User guide. Comments are unnecessary, I think.

Methodology (technology) of computer-aided design. If necessary, this document can contain a description of the process of software building, version control, testing, etc. But this is if the customer in the technical specification wishes to personally assemble the software. If he doesn’t require this (and doesn’t pay for it), then your entire internal kitchen is none of his business, and this document does not need to be done.

Technological instructions. Due to the fashion for formalizing business processes, a cunning customer sometimes tries to stuff operating regulations into this document. So, under no circumstances should you do this.

Description of business processes, role and job descriptions, work regulations - all this is ORD, that is, organizational and administrative documentation. Which is the product of a consulting project, which, as far as I understand, was not purchased from you. And they bought a technical project from you and also technical documentation for it.

The technological instruction is a layer between the operating instructions and the user manual. The RP describes in detail How you need to do certain actions in the system. The technological instruction says that which actions must be performed in certain cases related to the operation of the system. Roughly speaking, a technological instruction is a short digest of RP for a specific position or role. If the customer does not have roles formed or he wants you to create roles and job requirements yourself, include the most basic roles in the document, for example: operator, senior operator, administrator. The customer’s comments on the topic “but it’s not like that with us” or “we don’t like it” should be accompanied by a list of roles and a description of job responsibilities. Because business processes we we don't put it. We are these business processes automate.

I will write about the described rakes separately, with colorful examples, since this is not the first time that this has been repeated in different sectors of the “national economy.”

Description technological process data processing (including teleprocessing). A pathetic relic of the cave age, when there were specially designated “Computer Operators” who fed punched cards to the machine and packaged a printout of the result in an envelope. This instruction is for them. I can’t tell you exactly what to write in it in the 21st century. Get out yourself. The best thing is to just forget about this document.

System-wide solutions (WSO). The standard provides for 17 documents in the OP section. Firstly, these are almost all documents of the preliminary phase of Schematic Design. Secondly, these are all kinds of estimates, calculations and brief descriptions of automated functions. That is, information for people not from the main IT production, but for support staff - managers, estimators, purchasing specialists, economists, etc.

And thirdly, the OP includes a mega-document called “Explanatory Note to the Technical Project”, which is intended to be a kind of Executive Summary, but in fact, many designers shove all the useful content of the TP stage into it. Such a radical approach can be justified and even mutually beneficial for both the customer and the contractor, but in certain cases.

Options for using GOST 34

1. Full and exact adherence to the standard. Naturally, no one will write such a cloud of documents voluntarily. Therefore, a complete set of documents is prepared only at the urgent request of the customer, which he secured in the technical specifications and also pinned down with an agreement on top. In this case, you need to take everything literally and give the customer physical “books”, on which will be the names of the documents from Table 2 of GOST 34.201-89, with the exception of completely unnecessary ones, the list of which you must discuss and secure in writing. The contents of the documents must also, without any imagination, comply with RD 50-34.698-90, right down to the names of the sections. In order for the customer's brain to explode, sometimes big system are divided into subsystems, and separate design documentation is issued for each subsystem. It looks terrifying and is not subject to normal control with the help of the earthly mind. Especially regarding the integration of subsystems. Which greatly simplifies acceptance. The main thing is that you yourself do not get confused and that your system still works as it should.
2. We just love GOSTs. Serious big companies love standards. Because they help people understand each other better. If your customer is noted for his love of order and standardization, try to adhere to the standard GOST ideology when developing documents, even if this is not required by the technical specifications. The approving specialists will understand you better and approve of you, and you yourself will not forget to include them in the documentation important information, you will better see the target structure of documents, plan the work of writing them more accurately, and save yourself and your colleagues a lot of nerves and money.
3. We don't care about documentation, as long as everything works. The vanishing appearance of the irresponsible customer. A similar view of documentation can still be found among small and poor customers, as well as in authoritarian “idiotocracies” left over from the time of perestroika, where the boss is surrounded by loyal friends - directors, and all issues are resolved in personal conversations. In such conditions, you are free to neglect documentation altogether, but it is better, after all, not to knock down the sight and at least schematically fill in the documentation with content. If not to this customer, then pass it on (sell it) to the next one.

Conclusion

This article was about our GOST standards for documenting automated control systems. GOSTs are old, but, as it turns out, they are still very useful in the household. Apart from some obvious rudiments, the structure of the documentation has the properties of completeness and consistency, and adherence to the standard eliminates many project risks, the existence of which we may not be aware of at first.

I hope the material presented was useful to you, or at least interesting. Despite the apparent tedium, documentation is an important and responsible job, in which accuracy is as important as writing good code. Write good documents, colleagues! And next week I’m going on two business trips in a row, so I can’t guarantee the publication of new materials (I don’t have a cache, I’m writing from my head).

The Unified System of Documentation of Software Products - ESPD - belongs to GOST class 19 and is divided into 10 groups:
1. Fundamental Standards.
2. Rules for executing development documentation.
3. Rules for executing manufacturing documentation.
4. Rules for the implementation of support documentation.
5. Rules for the implementation of operational documentation.
6. Rules for circulation of software documentation.

Standard number 0 contains general provisions, standards 7 and 8 are reserved, and number 9 includes other standards not included in the first 6.

This brief descriptions GOST class 19; for more detailed information, please refer to the reference books.

• GOST 19.001-77 – one system software documentation.
• GOST 19.101-77 – types of programs and program documents.
• GOST 19.102-77 – stages of development of programs and program documentation.
• GOST 19.105-78 – requirements for the design of program documents, complexes and systems, regardless of their purpose and scope. GOST 19.105-78 contains a complete list of documentation that must accompany the completed software.

List of documentation declared by GOST 19.105-78:

1. Documents containing information necessary for the development of a software product and its manufacture.
1.1. Specification – the composition of the program and its documentation.
1.2. List of original holders - a list of enterprises where original program documentation is stored.
1.3. Program text – record the program text with the necessary comments.
1.4. Program description – information about the logical and functional structure of the program.
1.5. Test program and methodology – requirements to be verified when testing the program, procedure and methods for their control.
1.6. Terms of reference - the purpose and scope of the program, technical and special requirements, necessary stages and terms of development, types of tests.

1.7. Explanatory note – algorithm diagram, general description of the algorithm, function performed by the program. Explanation of the technical decisions made.

2. Documents used when operating the software product.
List of operational documents – a list of operational documents for the program.
Form – main characteristics of the program, completeness, general information about the use of the program.
Description of application - information about the purpose of the program, scope of application, class of tasks to be solved, restrictions on use, required configuration of hardware.
System Programmer's Guide - information for checking and ensuring functionality, setting up the program.
Programmer's Guide - information for operating the configured program.
Operator's manual - information to ensure the procedure for communication between the operator and the computer during program execution.
Language description – description of the syntax and semantics of the language used in the program.
Maintenance Manual - information for using test programs when servicing technical equipment.

Other GOSTs class 19:

• GOST 19.201-78 – the procedure for constructing and preparing technical specifications for the development of a program or software product.
• GOST 19.202-78 – form and procedure for drawing up specifications for software products defined in GOST 19.101-77.
• GOST 19.301-79 – program and methodology for testing software products.
• GOST 19.401-78 – the procedure for constructing and formatting program text when developing software products.
• GOST 19.402-78 – description of the program.
• GOST 19.403-79 – form of completion and content of the list of original holders, defined in GOST 19.105-78.
• GOST 19.404-79 – form of completion and content of the explanatory note, defined in GOST 19.105-78.
• GOST 19.501-78 – form of filling out and contents of the form for a software product, defined in GOST 19.105-78.
• GOST 19.502-78 – form of filling and content of the application description defined in GOST 19.105-78.
• GOST 19.503-79 – form of completion and content of the system programmer’s manual, defined in GOST 19.105-78.
• GOST 19.504-79 – form of completion and content of the programmer’s manual, defined in GOST 19.105-78.
• GOST 19.505-79 – form of completion and content of the operator’s manual, defined in GOST 19.105-78.
• GOST 19.506-79 – form of completion and content of the description of the language defined in GOST 19.105-78.
• GOST 19.507-79 – form of completion and content of the list of operational documents, defined in GOST 19.105-78.
• GOST 19.508-79 – form of completion and content of the maintenance manual, defined in GOST 19.105-78.
• GOST 19.701-90 – diagrams of algorithms, programs, data and systems.