one system program documentation. Schemes of algorithms and programs. Execution rules.
Unified system of program documentation. Schemes of algorithms and programs. Conventional graphic symbols
Unified system of program documentation. Terms and Definitions.
Unified system of program documentation. P-schemes of algorithms and programs.
Unified system of program documentation. Types of programs and program documents.
Unified system of program documentation. Development stages.
Unified system of program documentation. Designations of programs and program documents.
Unified system of program documentation. Basic inscriptions.
Unified system of program documentation. General requirements to program documents.
Unified system of program documentation. Requirements for printed program documents.
Unified system of program documentation. Technical task. Requirements for content and design.
Unified system of program documentation. Specification. Requirements for content and design.
Unified system of program documentation. Test program and methodology. Requirements for content and design.
Unified system of program documentation. Program text. Requirements for content and design.
Unified system of program documentation. Program description.
Unified system of program documentation. List of original holders.
Unified system of program documentation. Explanatory note. Requirements for content and design.
Unified system of program documentation. Form. Requirements for content and design.
Unified system of program documentation. General description. Requirements for creation and design.
Unified system of program documentation. System Programmer's Guide. Requirements for content and design.
Unified system of program documentation. Programmer's Guide. Requirements for content and design.
Unified system of program documentation. Operator's manual. Requirements for content and design.
Unified system of program documentation. Description of the language. Requirements for content and design.
Unified system of program documentation. List of operational documents.
Unified system of program documentation. Guide maintenance. Requirements for content and design.
Unified system of program documentation. General rules duplication, accounting and storage.
Unified system of program documentation. Rules for duplication, accounting and storage of printed program documents.
Unified system of program documentation. General rules for making changes.
Unified system of program documentation. Rules for making changes to program documents made in print.
GOST 19.101-77
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
MKS 35.080
Date of introduction 1980-01-01
By Resolution of the State Committee of Standards of the Council of Ministers of the USSR dated May 20, 1977 N 1268, the introduction date was set at 01/01/80
EDITION (January 2010) with Amendment No. 1, approved in June 1981 (IUS 9-81).
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. 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
Program type | Definition |
Component | A program considered as a whole, performing a complete function and used independently or as part of a complex |
Complex | A program consisting of two or more components and (or) complexes that perform interrelated functions, and is used independently or as part of another complex |
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.
table 2
Type of program 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 the program, as well as the procedure and methods for their control |
|
Technical task | Purpose and scope of the program, technical, feasibility and special requirements for the program, necessary stages and terms of development, types of tests |
Explanatory note | Algorithm diagram, general description algorithm and (or) functioning 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
Type of 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, methods used, class of problems solved, restrictions for use, minimum configuration technical means |
Information for checking, ensuring the functioning 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 |
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
Code | Document type | Development stages |
|||
Preliminary design | Technical project | Working draft |
|||
component | complex |
||||
Specification | |||||
List of original holders | |||||
Program text | |||||
Program description | |||||
List of operational documents | |||||
Form | |||||
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;
- 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 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).
Electronic document text
prepared by Kodeks JSC and verified against:
official publication
Unified software system
documentation: Sat. GOST. -
M.: Standartinform, 2010
At one time, when I was just starting to work as a programmer, I often heard “please write documentation for your program.” I honestly described everything, gave it to my boss, after which the black magic session began. After a while, the boss called me and began to mumble inarticulate sounds, crumple the printout of my “best” text in his hands, darting his eyes. The general meaning of his mooing was that it turned out “wrong,” “wrong,” and “look at what others are doing.” Since it was impossible to extract any other answer from him, I went to “others” for examples of documents. As a rule, these were cheerful guys, the meaning of whose speeches was that “here are examples,” “in general, according to GOST,” and “no one needs all this.” This is how I learned for the first time that a programmer can come into contact with terrible GOST standards.
It is amazing that among many dozens of my colleagues, very intelligent programmers, there was no one who would treat GOSTs differently. Even the few people who knew them and, it seemed, even knew how to draw up documents, treated them with contempt and formality. A situation where even the people responsible for development management do not understand why GOSTs are needed and how they will be applied occurs in many enterprises all the time. Yes, there were companies that understood how the “Program Description” differs from the “Description of Application,” but there were a clear minority of them. On the Internet, the prevailing point of view is that GOSTs for programmers are an obvious rudiment, and are needed only if they “bend” to them. The draft design is considered “a relatively fair way of taking away excess banknotes from the customer.” I had to delve into and understand it relatively recently - in the process of developing a requirements management system tailored to domestic specifics. Documentation which, of course, must be generated “according to GOST”.
Here I want to focus on only one topic that a programmer in domestic enterprises, especially in research institutes, has to deal with - the set of ESPD standards. I don’t consider myself a great expert on the ESPD - there are people who have been working on it for decades and will certainly correct me. The article rather tries to outline the outlines of a “road map” for those who are just getting into the swing of things.
Standards
Let's take a brief look at what standards there are (focusing on the IT area).- international. A distinctive feature is that it has been adopted by an international organization. An example of such an organization is ISO (International Organization for Standardization). An example of its standard: ISO 2382-12:1988 (Peripheral equipment). Joint standards of ISO and the International Electrotechnical Commission (IEC, in Russian - IEC) are widespread: for example, ISO/IEC 12207:2008 ( life cycle BY);
- regional. A distinctive feature - adopted by the regional commission for standardization. For example, many Soviet GOSTs are now regional standards, because adopted by the interstate council, which includes some former Soviet republics. This council also adopts new standards - and they also receive the GOST designation. Example: GOST 12.4.240-2013;
- standards of public associations; For example, the same IEC: IEC 60255;
- national standards. For Russia, the beginning of such standards is “GOST R”. There can be three types:
- exact copies of international or regional ones. They are designated indistinguishably from “self-written” (national, independently written);
- copies of international or regional with additions. They are indicated by adding to the cipher of the domestic standard the international cipher, which was taken as a basis. For example: GOST R ISO/IEC 12207;
- actually, national standards. For example, GOST R 34.11-94.
The notation systems at each level and in each organization are different; each case will have to be analyzed separately. To quickly understand “whose” standard is before your eyes, you can use a cheat sheet.
GOST
So: standards are international, interstate (regional) and national. GOST, as we found out, is a regional standard. GOSTs have a rather confusing, in my opinion, notation system. It is fully set out in GOST R 1.5-2004, I will give the minimum to navigate it. Firstly, it is necessary to distinguish between the GOST designation and its classification. The designation is, roughly speaking, unique identificator standard A classifier code is an auxiliary code that helps to find a standard or determine which area of knowledge it belongs to. There can be many classifiers, mainly two are used: KGS (classifier of state standards) and its successor OKS (all-Russian classifier of standards). For example: “GOST R 50628-2000“ is the designation of the standard. From the designation it is only clear that it was adopted in 2000. It has an OKS code “33.100;35.160”: i.e. “33” - section “Telecommunications, audio, video”, “100” - subsection “electromagnetic compatibility”. However, it is also included in the 35.160 classifier branch. “35” - “ Information Technology. Office machines”, “160” - “Microprocessor systems...”. And according to the KGS it has the code “E02”, which means “E” - “Electronic technology, radio electronics and communications”, “0” - “General rules and regulations for electronic technology, radio electronics and communications”, etc.If you know the designation of the standard, then you can get its codes for KGS and OKS, for example, on this smart website.
So, let's return to the GOST designations. There can be two options:
- standard refers to a series of standards. In this case, after the standard category index (for example, GOST, GOST R or GOST RV) there is a series code, a dot and the designation of the standard within the series. The rules for designating standards within a series are established by the rules of the series. For example: GOST RV 15.201-2000, GOST R 22.8.0-99, GOST 19.101-77;
- The standard does not belong to a series of standards. Then after the category index there is simply a serial number of the standard, a dash and the year of adoption. For example, GOST R 50628-2000.
ESPD
ESPD is one of these GOST series, number 19. That is. all standards related to ESPD begin with the prefix “19.”: for example, GOST 19.106-78. Stands for “Unified System of Program Documentation”. There are other series:- GOST ESKD ( one system design documentation, prefix “2.”);
- GOST ESTD (unified system of technological documentation, prefix “3.”);
- GOST R, System for development and production of products, prefix “15.”;
- GOST RV, Armament and military equipment. System for developing and launching products into production, prefix “15.”;
- GOST, System technical documentation on ACS, prefix “24.”;
- GOST, Set of standards for automated systems, prefix “34.”.
19.001-77. General provisions
Describes the rules for assigning designations to standards in the ESPD series. Not needed in practical life.19.102-80. Schemes of algorithms and programs. Execution rules.
Describes the rules for constructing and designing algorithms. Uses notation from 19.103. In my practice, the only time it was needed was when the certification laboratory insisted on a formal basis that it was the algorithm diagram that was needed. From my point of view, classic flowcharts are a thing of the past, and the only place where they remain more or less appropriate is if, when presenting, the author wants to focus the reader’s attention on the algorithm.19.003-80. Schemes of algorithms and programs. Conventional graphic symbols
Given graphic symbols valid types of flowchart elements. Required if flowcharts are used.19.004-80. Terms and Definitions.
Meager glossary. The most interesting thing is that it contains formal definitions of program and operational documents.19.005-85. P-schemes of algorithms and programs
Almost a forgotten language. At one time, P-schemes were widely used in the rocket and space industry, becoming the de facto standard for writing launch control programs and simulating launches. However, now this language is completely forgotten. In my work, I have never encountered P-schemes. Although, compared to block diagrams, they have noticeable advantages: they are compact, suitable for visualizing nonlinear algorithms (for example, classes in C++) or data structures. At the same time, there is practically no information on them on the Internet: I found this and this site useful. In any case, if I now had to insert an algorithm diagram into the software documentation, I would choose P-charts rather than flowcharts.19.101-77. Types of programs and program documents
Contains a table of correspondence between a document type and its code, as well as a division of document types into operational and program. The concept of complex and component is introduced. There is nothing else useful.19.102-77. Development stages
An important and necessary standard that describes the types of documents and provides codes for the types of program documents. This standard (together with 19.103-77) is one of the keys to “unraveling” the designations of documents like ABVG.10473-01 32 01-1.The standard introduces the concept of a complex and a component (a number of enterprises add a third type - a set, when it comes to unrelated software elements), and a division is given: which documents are operational and which are not.
You should be careful with Table 4, which shows which document is being executed at which stage of development. The stages of development are usually regulated in standards for the implementation of design and development work, and it is also indicated there which documents must be presented to the customer at each stage.
19.102-77. Development stages
In my memory, this standard has never been used: who does what at what stage and what they report on is written down in the technical specifications or a reference is made to GOSTs, where this is more clearly stated (for example, GOST RV 15.203). At the same time, for a beginner, it contains a fairly succinct outline of work on the main stages of OCD.19.103-77. Designations of programs and program documents
It is needed mainly in order to learn to read the symbols of documents similar to the one given above. However, understanding the notation is useful when you have to go beyond standard work: for example, remember that documents with codes after 90 are user-defined, i.e. any. In my practice, we released document 93, which we called “Program Documentation Statement”, document 96 - “Assembly Instructions”.The common phrase “execution option” is absent from the ESPD and is replaced by “revision number”. On the one hand, this is not entirely correct: the revision number was intended to track the evolution of the program: first the first edition is released, then, for example, after revision, the second. But in practice, when you need to release a software version for several operating systems(cross-platform software), there is no other choice. More precisely, there is, but it is incorrect: assign the version for each operating system its own designation - and put in the archive several disks with source codes (according to the number of operating systems), develop (in fact, copy) the entire set of documentation, etc.... That is. pure stupid and confusing activity. The solution in the form of assigning a version number to each operating system makes it possible to make some documents common.
The ESPD uses the designation of the source code of the program and the result of the assembly as “documents,” which confuses many programmers. The document “program text”, according to 19.101-77, has the designation 12. It is further accepted that the source code is designated as 12 01 - i.e. 01 (the first) document of type 12, and binaries - like 12 02 - i.e. the second document of type 12. In some cases, additional tools are required to build a program - compilers, installer generators, etc. Those. programs that are not included in the delivery, but are needed for assembly. A solution might be to designate them as 12 03 - i.e. third document of type 12.
19.104-78. Basic inscriptions
Describes two sheets of the document - the approval sheet (LA) and title page. The approval sheet in the ESPD contains signatures of both the authorities who approved the document and the developers, normative inspectors, acceptance representatives, etc. Those. it contains quite a lot of sensitive information for the enterprise. Therefore, the standard assumes that the LU remains at the development enterprise and is sent only upon special instructions. Once again, the LU is not part of the document, but is, as it were, a separate document, and it is included in the specification as a separate line.The initially confusing oddity in the separation of the LU from the document itself has very good reasons:
- as already mentioned, often an enterprise does not want to disclose information about the developer. Separating the LU and “squeezing” it allows this to be done (unlike the ESKD, there is no stamp on the document sheets in the ESPD; all information is localized only in the LU);
- A number of enterprises use mixed document flow: original documents are stored in in electronic format in the archives of the enterprise, and the license plates on them (with original signatures) - in paper;
It should also be remembered that the LU is not numbered, and the first page is the title page, and the first page on which the number is placed is next to the title page. But if there is more than one LU (this happens if all the signatures do not fit on the sheet), then the LUs are numbered separately.
19.105-78. General requirements for program documents
The general structure of the document is introduced, regardless of the method of its execution. Those. Back in 1978, it was laid down in the standard that a document may not necessarily be paper. In particular, the concept of content is introduced for completely electronic documents. For paper execution, common at that time, GOST 19.106-78 was adopted.Currently, one rarely has to refer to this standard: unless one forgets the order of the main parts of the document.
19.106-78. General requirements for printed program documents
The most comprehensive standard from the ESPD, second only to the description of R-schemes. It is the main working standard when preparing documentation. Introduces rules for formatting text, document structure elements, images, formulas, etc. However, unlike the corresponding 2.106 from the ESKD, 19.106 is significantly less detailed, which leads to numerous uncertainties.Firstly, the standard does not actually define line spacing and the amount of vertical space between headings. He introduces three rules for determining spacing: for typewritten text, machine and typographical.
Typescript is text typed on a typewriter. The shift of the next line relative to the previous one was carried out automatically during the so-called “carriage return” - the transition to printing the next line, produced by moving a special lever. Typically, the spacing could be manually adjusted by turning the paper feed shaft, and had a “setting” that allowed you to set the spacing size - single or double.
Machine type is most likely the printed text. But for him there is only an indication that the result must be suitable for microfilming. This is an implicit reference to 13.1.002-2003, which, unfortunately, sets line spacing (and, by the way, the minimum font height) only for handwritten documents (clause 4.2.5).
Typographic - text typed in a printing house. Considering the year the standard was adopted, most likely we are talking about
[letterpress printing, where line spacing was determined by the type used. I am not an expert in typography, and there is very little information about typesetting methods right now.
Which interval to use in the end is often determined by local regulations or service stations. Typical values are one and a half spacing and font size 14.
The way a document is structured often raises many questions. 19.106 considers that the entire document is divided into sections, subsections, paragraphs and subparagraphs. All of them (except for sections and subsections) may or may not have a title. Wherein:
- “the contents of the document include the number of sections, subsections, clauses and subclauses that have a title” (clause 2.1.4). This is a direct indication that the subclause may have a title and be included in the table of contents;
- “it is allowed to place text between section and subsection headings, between subsection and paragraph headings.” It is important to note that unnumbered text can only be between headings, and only on the top 2 levels.
This standard has a number of “holes” and inconsistencies. For example, it is said: “illustrations, if they are in this document more than one, are numbered in Arabic numerals throughout the document. “But if there is only one illustration, then it is not numbered, and then how can you refer to it? The same goes for tables. For footnotes, GOST does not indicate the method of their numbering - within the entire document or within the page.
Tables. The document itself contains a reference to GOST 1.5.68. Judging by the first episode, it is easy to conclude that this is a standard for developing standards. What he has to do with it is unclear. In meaning, it corresponds to the rules for designing tables in the ESKD, with minor exceptions. This standard was canceled and replaced, through several iterations, by 1.5-2012, in which the table design rules... simply disappeared. Back in 1.5-2002 they were there, but already in 1.5-2004 they disappeared. IN real life We draw up tables in accordance with the ESKD.
Applications. The standard does not indicate whether figures, formulas and tables from the appendices are included in the general list. Similarly, it is not said whether the table of contents needs to disclose the structure of the application if it contains its own sections, paragraphs, etc. In our practice, we do not disclose the insides of applications.
Finally, something should be said about indentation. A paragraph indent of 5 characters is common for:
- red line;
- indentation of a document structure element after a section (subsection, clause, subclause);
- enumeration element.
In this case, the text located on the next line after the indented line is aligned to the left margin. Often there are errors when the indentation jumps - the red line - one value, the item number - us with a different interval, in nested indentations in lists - this is generally necessary.
In the following parts I plan to get to the end of the list of ESPD standards.
ESPD – refers to complex systems of general technical standards
ESPD is a system of interstate standards of the CIS countries operating in the Russian Federation, based on an interstate agreement on standardization. ESPD standards cover that part of the documentation that is created during the development of software and is mostly associated with documenting the functional characteristics of software. ESPD standards are advisory in nature
ESPD is a set of state standards that establish interconnected rules for the development, execution and circulation of programs and program documentation
ESPD standards establish requirements governing the development, support, production and operation of programs, which ensures the ability to:
1. Unification of software products for mutual exchange of programs and the use of previously developed programs in new developments
2. Reducing labor intensity and increasing the efficiency of development, maintenance, production and operation of software products
3. Automation, production and storage of program documentation
Program maintenance includes analysis of the functioning, development and improvement of the program, as well as making changes to it in order to eliminate errors
The rules and regulations established in the ESPD standards apply to programs and software documentation for subtractive machines, complexes and systems, regardless of their purpose and scope of application
The ESPD includes:
1. Fundamental and organizational and methodological standards
2. Standards defining the forms and content of program documents used in data processing
3. Standards that ensure automation of the development of program documents
The development of organizational and methodological documentation that defines and regulates the activities of organizations for the development, maintenance and operation of programs should be carried out on the basis of ESPD standards
ESPD standards are divided into classification groups
ESPD standards are designated as follows:
GOST 19.001-77
19 – standards belonging to the ESPD
0 – General provisions
77 – year of approval
GOST 19.503-79- system programmer's guide. Requirements for content and design. Abstract and content are required. The system programmer's manual should contain the following sections:
1. General information About the program
Purpose and functions of the program and information about the hardware and software that ensures the execution of this program
2. Program structure
Information about the structure of the program, its components, connections between components and about connections with other programs
3. Setting up the program
Description of steps to configure the program for a specific application (adjustment to the composition of hardware, selection of functions, etc.)
4. Checking the program
Description of testing methods that allow us to give general conclusions about the performance of the program (test examples, running methods, results)
5. Additional features
Description of additional sections, functionality programs and ways to select them
6. Message to the system programmer
Texts of messages issued during program execution, description of their content and actions that must be performed on these messages
7. List of documents
Depending on the specifics of the document, it is possible to combine individual sections and introduce new ones. In justified cases, the section “ additional features» do not include, but in the names of sections - omit the word program, or replace it with the name of the program
The appendix to the system programmer's manual may contain additional materials (examples, illustrations, tables, graphs...)
GOST 19.504-79- programmer's guide. Requirements for content and design. Abstract and content are required. The programmer's manual should contain the following sections:
1. Purpose and conditions of use
Purpose and functions, conditions necessary for execution (volume of RAM, requirements for composition and parameters peripheral devices, software requirements)
2. Program characteristics
Description of the main characteristics and features of the program (time characteristics, operating mode, means of monitoring the correct execution and self-healing of the program)
3. Access to the program
Description of program call procedures (methods of transferring control and data parameters)
4. I/O data
Description of the organization of I/O information and, if necessary, its coding
5. Message
Texts of messages issued to the programmer or operator during program execution, a description of their content and actions that must be performed on these messages
6. List of documents
Depending on the specifics of the document, it is possible to combine individual sections and introduce new ones. The appendix to the programmer's manual may contain additional materials (examples, illustrations, tables, graphs...)
GOST 19.505-79- operator's manual. Requirements for content and design. Abstract and content are required. The operator's manual should contain the following sections:
1. Purpose of the program
Information about the purpose and information sufficient to understand the functions of the program and its operation
2. Conditions for program execution
Conditions necessary for program execution (minimum and (or) maximum composition of hardware and software)
3. Execution of the program
The sequence of operator actions that ensure loading, launching and terminating the program (a description of the functions, format and possible options of commands with which the operator loads and controls the execution of the program, as well as the program’s responses to these commands should be provided
4. Message to the operator
Texts of messages issued during program execution, description of their content and corresponding operator actions (operator actions in case of failure, possibility of restarting the program...)
5. List of documents
Depending on the specifics of the document, it is possible to combine individual sections and introduce new ones. It is allowed to illustrate the contents of sections with explanatory examples, tables, diagrams and graphs. In the appendix to the operator's manual it is allowed to include various materials that are inappropriate to include in sections of the manual