Registration of program documentation according to the espd, espd. Rules for preparing coursework and diploma papers General characteristics of the condition

G O S U D A R S T V E N N Y S T A N D A R T S O Y W A S S R

By Decree of the USSR State Committee on Standards dated May 14, 1980 No. 2101, the introduction date was established

from 01/01/1981

This standard applies to technical documentation for automated control systems (ACS) of all types, developed for all levels of management (except for national ones), and establishes requirements for the content of documents included in accordance with GOST 24.101-80 as part of the software documentation in ACS projects.

1. GENERAL PROVISIONS

1.1. The software documentation is intended to:

• to describe design solutions for software in the document “Description of ACS Software”.
• to establish requirements for a program (set of programs) in the “Technical Specifications” document;
• to describe solutions that provide maintenance, production and operation of a program (set of programs) in the documents “Explanatory Note”, “Description of Application”, “Description of the Program”, “Specification”, “Programmer’s Guide”, “Operator’s Guide”, “Program Text” , “Form”, “Procedure and testing methods”;
• to check the functionality of the program (set of programs) in the document “Description of the test case”.

1.2. When developing documents for parts of an automated control system, the content of sections of each document is limited to the framework of the corresponding part.

1.3. Depending on the purpose and specific features of the created automated control systems, it is allowed to include additional sections in documents, the content requirements of which are not established by this standard. The absence of design solutions for a section of the document is recorded in the appropriate section with the necessary explanations.

1.4. Requirements for the content of documents “Technical Specifications”, “Explanatory Note”, “Description of Application”, “Specification”, “Operator’s Manual”, “Program Text”, “Form”, “Test Procedure and Methodology” are established by GOST 19.201-78, GOST 19.404-79, GOST 19.502-78, GOST 19.202-78, GOST 19.505-79, GOST 19.401-78, GOST 19.501-78 and GOST 19.301-79.

(Changed edition, Amendment No. 1).

2. REQUIREMENTS FOR THE CONTENT OF DOCUMENTS

2.1. Description of ACS software

2.1.1. The document must contain an introductory part and sections:

• software structure;
• the main functions of the software parts;
• software development methods and tools;
• operating system;
• tools that expand the capabilities of the operating system.

2.1.2. The introductory part should contain basic information about the technical, information and other types of automated control system support necessary for software development, or a link to the relevant documents of the automated control system project.

2.1.3. The “Software Structure” section should contain a list of software parts, indicating their relationships and the rationale for identifying each of them.

2.1.4. The section “Main functions of software parts” should contain subsections in which, for each part of the software, the purpose and description of the main functions are given.

(Changed edition, Amendment No. 1).

2.1.5. The section “Methods and tools for software development” should contain a list of programming methods and tools for developing automated control system software, indicating parts of the software in the development of which appropriate methods and tools should be used.

2.1.6. The "Operating System" section should contain:

• name, designation and brief description of the selected operating system and its version, within which the developed programs will be executed, with justification for the choice and indication of sources where a detailed description of the selected version is given;
• the name of the manual in accordance with which the selected version of the operating system should be generated;
• requirements for the generation option of the selected operating system version.

2.1.7. The “Tools that extend the capabilities of the operating system” section should contain subsections in which, for each tool used that extends the capabilities of the operating system, you should indicate:

• name, designation and brief description of the product, justifying the need for its use and indicating the source, which provides a detailed description of the selected product;
• the name of the manual in accordance with which the product used should be configured for a specific application;
• requirements for setting up the tool used.

2.2. Description of the program

2.2.2. For a program (set of programs) obtained through the use of previously developed software, the “Program Description” document should be supplemented with the “Software Setup” section.

2.2.3. The “Software Configuration” section should contain:

• name, designation of the software used, description of the procedures required to configure them, or links to the operational documentation of these tools;
• a list of elements of used software necessary to obtain the program (set of programs);
• description of the settings in the language provided in the operational documentation for the software used.

2.3. Programmer's Guide

2.3.1. The document on the composition of the sections and their content must comply with GOST 19.504-79 and, in addition, include the section “Information on the form of presentation of the program (set of programs).”

2.3.2. The section “Information about the form of presentation of the program (set of programs)” must contain information about the medium on which the program is recorded, about the content and coding system of information recorded on the medium, as well as information necessary for reading information from the medium.

2.3.3. For a program (set of programs) that can be customized to the conditions of a specific application, the “Programmer’s Guide” document includes sections:

• program structure;
• program settings;
• additional features;
• messages to the system programmer.

2.3.4. It is allowed for a program (set of programs) that can be customized to the conditions of a specific application, instead of the sections listed in clause 2.3.3, to develop a separate document “System Programmer’s Guide” that meets the requirements of GOST 19.503-79.

2.4. Test case description

2.4.1. The document must contain sections:

• appointment;
• source data;
• calculation results;
• checking a program (set of programs).

2.4.2. The “Purpose” section should contain a list of parameters and a brief description of the function that is implemented by the program (set of programs) that is tested by the test example.

2.4.3. The “Initial data” section must contain a description of the initial data for testing the program (set of programs) with the presentation of the initial data. It is allowed to present the source data in the form of a printout from the ADCP.

2.4.4. The “Calculation Results” section should contain the results of processing the initial data by a program (set of programs), allowing one to evaluate the correct execution of the functions being tested and the value of the parameters being tested. It is allowed to present the calculation results in the form of a printout from the ADCP.

2.4.5. The section “Checking the program (set of programs)” should contain:

• a description of the composition of the technical means necessary for the operation of the program (set of programs), or a link to the relevant program documents;
• description of procedures for generating initial data for checking a program (set of programs), calling the program (set of programs) being tested and obtaining calculation results;
• description of the operator’s actions when preparing initial data and testing a program (set of programs) using a test example.

Computer programs are drawn up in accordance with the requirements of the Unified System of Program Documentation (USPD). 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 a section there must be continuous numbering for all subsections, paragraphs and subparagraphs included in this section.
• The numbering of subsections includes the section number and the serial number of the 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 a footnote refers to a single word, the footnote sign is placed directly next to this word, but if it refers to a 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.
• Each application must begin on a new page with the word “APPENDIX” indicated 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.

Software documentation is an integral component of the software product and must be drawn up in accordance with the Unified System of Software Documentation (USPD - GOST series 19). As part of educational work, it is allowed to include the entire content of the program documentation in a single “program report”, while the formal requirements for the preparation of such a report correspond to the requirements for a research report. Program documentation, in addition to formal documents (specification, list of original holders, form, etc.), includes:

• · Technical specifications (purpose, scope of application of the program, requirements for the program).
• · Text of the program (record of the program with the necessary comments).
• · Description of the program (information about the logical structure and functioning of the program).
• · Explanatory note (algorithm diagram, general description of the algorithm and/or program functioning, rationale for decisions made).
• · Operating documents.

The program document “Explanatory Note” is drawn up at the stage of preliminary or technical projects of the program. Typically not used at the detailed design stage.

Operational documents include:

• · Description of the application (information about the purpose of the program, scope, methods used, class of problems to be solved, restrictions for use, minimum configuration of hardware).
• · System Programmer's Guide (information for checking, ensuring the functioning and setting up the program for the conditions of a specific application).
• · Programmer's Guide (information for operating the program).
• · Operator's manual (information to ensure communication between the operator and the computer system during program execution).
• · Description of the language (description of the syntax and semantics of the language).
• · Maintenance manual (information for using test and diagnostic programs when servicing technical equipment).

The main part of the software documentation is compiled at the detailed design stage. The need for a particular document is determined at the stage of drawing up technical specifications. It is allowed to combine certain types of documents. The operational document “Language Description” is included in the program documentation if the developed software product implements a certain programming language, task management, organization of the computing process, etc. The operational document “Maintenance Manual” is included in the program documentation if the developed software product requires the use test or diagnostic programs.

Program text is a symbolic representation of a source or intermediate language, or a symbolic representation of machine codes. The program text is formatted in a monospace font (Courier, Lucida Console, etc.) in accordance with generally accepted design standards:

• 1. The number of operators on a line must be equal to 1.
• 2. All statements included in a compound statement must be shifted to the right by the same number of positions, and the operator brackets (i.e., what delimits the compound statement) belonging to the same block must be placed as follows: the opening bracket must be located on the same line as the statement that opens the block, and the closing line must be in the same column from which the statement that opens the block begins. It is permissible to place the opening parenthesis on the line following the statement that opens the block, in the same column with which that statement begins.
• 3. The entire source text line of the program must be located on one typographic line (up to 80 characters depending on the font). Failure to comply with this rule indicates too much nesting of blocks, which means an unsuccessful algorithm or program structure. In this case, it is recommended to rethink the structure of the program, introduce additional functions, replacing some large parts of the code with their calls, redo the algorithm, etc.
• 4. If the language syntax allows, it is advisable to separate operation signs with spaces from the operands. As in regular text, commas must be followed by a space.
• 5. Function definitions or logical parts of the program should be separated from each other by blank lines.
• 6. Identifiers (names of variables, types, subroutines) must be so meaningful that the reader of the program text can understand their meaning without the presence of the author. If necessary, a variable or type declaration can be accompanied by a comment.
• 7. The text of the program must contain comments reflecting the functional purpose of a particular program block and the structure of the program.

Document Description of the program contains:

• · General information (designation, name of the program, software necessary for the operation of the program, programming languages ​​in which the program is written);
• · Functional purpose (classes of tasks to be solved, information about functional restrictions on application);
• · Description of the logical structure (program algorithm, methods used, program structure with a description of the components and connections between them);
• · The technical means used (types of computers and devices that are used when running the program);
• · Call and load (method of calling a program from the corresponding storage medium);
• · Input data (nature, organization and preliminary preparation of input data, as well as their format, description and coding method);
• · Output data (the nature and organization of the output data, as well as its format, description and coding method).

The description of the logical structure of the program should be accompanied by a block diagram of the program. The “Program Description” document may also contain data diagrams, program interaction diagrams, system resource diagrams, etc., designed in accordance with GOST 19.701-90.

Document Description of application refers to operational documents and consists of the following sections:

• · Purpose of the program (capabilities, main characteristics, limitations of the scope).
• · Application conditions (requirements for hardware and software, general characteristics of input and output information, as well as requirements and conditions of an organizational, technical and technological nature).
• · Description of the problem (definitions of the problem and methods for solving it are indicated).
• · Input and output data.

Document System Programmer's Guide refers to operational documents and is included in program documentation if the developed software product requires maintenance by a system programmer. The document consists of the following sections:

• · General information about the program (the purpose and functions of the program, information about the hardware and software that ensures the execution of this program).
• · Program structure (information about the structure, relationships between program modules and with other programs).
• * Setting up the program (setting up the composition of technical means, selecting functions)/
• * Program verification (verification methods and techniques, test cases, running methods, results).
• * Additional features.
• * Messages to the system programmer (texts of messages issued during configuration, program testing, during program execution and a description of the actions that must be taken in response to these messages).

The document Programmer's Guide refers to operational documents and is included in the program documentation if the developed software product requires maintenance by a programmer. The document consists of the following sections:

• * Purpose and conditions of use of the program (purpose and functions of the program, information about the hardware and software that ensures the execution of this program).
• * Characteristics of the program (time characteristics, operating modes, means of monitoring the correct execution, etc.).
• * Access to the program (methods of transferring control and data parameters).
• * Input and output data (format and encoding).
• * Messages (texts of messages issued to the programmer or operator during program execution and a description of the actions that must be taken in response to these messages).

The document Operator's Manual refers to operational documents and consists of the following sections:

• * Purpose of the program (information sufficient to understand the functions of the program and its operation);
• * Conditions for program execution (minimum and/or maximum set of hardware and software, etc.);
• * Program execution (a sequence of operator actions that ensure loading, launching, executing and terminating the program; describes the functions, formats and possible versions of commands with which the operator loads and controls the execution of the program, as well as the program’s responses to these commands);
• * Messages to the operator (texts of messages issued to the operator during program execution and a description of the actions that must be taken in response to these messages).

When preparing text and graphic materials included in the program documentation, you should adhere to current standards. Some provisions of these standards are given below. Design of text and graphic material. Text documents are drawn up on A4 size sheets, while graphic material can be presented on A3 size sheets. The margins on the sheet are determined in accordance with the general requirements: left - at least 30, right - at least 10, top - at least 15, and bottom - at least 20 mm. In text editors for designing a note, page parameters are ordered depending on the printing device. When manually completing documents, page parameters are selected for convenience. All pages are numbered continuously. The number is indicated on the top right with an Arabic numeral. Pages include both sheets with texts and pictures, and sheets of applications. The first page is considered to be the title page. The page number is not indicated on the title page. The names of sections are written in capital letters in the middle of the line. The distance between headings and text, as well as between section and subsection headings, should be equal to:

• * When executing a document by typewriting - two intervals.
• * When done handwritten - 10 mm.

The names of subsections and paragraphs should be placed in paragraph indentation and printed in spaced form with a capital letter, without underlining and without a period at the end. The distance between the last line of text of the previous section and the subsequent heading, when located on one page, should be equal to:

• * When executing a document by typewriting - three intervals.
• * When done handwritten - at least 15 mm.
• * When using text editors - determined by the capabilities of the editor.

Sections and subsections are numbered in Arabic numerals with a dot. Sections must have serial numbers 1, 2, etc. The subsection number includes the section number and the serial number of the subsection included in this section, separated by a dot. For example: 2.1, 3.5. References to clauses, sections and subsections are indicated using the serial number of the section or clause, for example, “in section. 4", "in clause 3.3.4". The text of sections is printed at 1.5-2 intervals. When using text editors, the height of letters and numbers must be at least 1.8 mm (fonts No. 11-12). Listings should be numbered in Arabic numerals with a bracket, for example: 2), 3), etc. - with a paragraph indent. It is allowed to highlight an enumeration by placing a hyphen before a text item or a symbol that replaces it in text editors. Design of drawings, algorithm diagrams, tables and formulas. In accordance with GOST 2.105-79 “General requirements for text documents,” illustrations (graphs, diagrams, diagrams) can be given both in the main text and in the appendix. All illustrations are called drawings. All figures, tables and formulas are numbered in Arabic numerals sequentially (continuous numbering) or within a section (relative numbering). In the application - within the application. Each drawing must have a caption - a title placed under the drawing, for example: Fig. 12. Form of the main menu window.

All figures, tables and formulas in the note must have links in the form: “(Fig. 12)” or “the form of the main menu window is shown in Fig. 12". If space permits, figures and tables should be placed immediately after the paragraph in which they are first mentioned, or as close as possible to that paragraph on subsequent pages. If a drawing occupies more than one page, all pages except the first are marked with the drawing number and the word “Continuation.” For example: Fig. 12. Continued.

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

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

The table number is placed in the upper right corner or before the table title, if there is one. The title, except for the first letter, is written in lowercase letters. References to tables in the text of the explanatory note are indicated in the form of the word “table.” and table numbers. For example: The test results are shown in table. 4.

The formula number is placed on the right side of the page in parentheses at the formula level. For example: z:=sin(x)+ln(y); (12)

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

Figures and tables placed in the appendix are numbered in Arabic numerals within each appendix with the addition of the letter “P”, For example: Fig. Item 12 - 12th drawing of the application; Rice. P1.2 - 2nd picture of the 1st appendix.

If the application contains the text of the program, then each file is designed as a drawing with the name of the file and its purpose, for example: Fig. P2.4. The file menuran.pas is a program for moving the cursor of the main menu.

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

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

Thus, we looked at how to correctly draw up documentation so that there are no complaints from the customer about it. We examined in detail what documents such as program text, program description, application description, system programmer's manual, programmer's manual, operator's manual contain, and how to prepare these documents.

V.E. Karpov

This document contains a brief description of the ESPD standards, knowledge of which is necessary for students to complete coursework and projects related to the creation of software systems. In addition, it can be useful from the point of view of improving the quality of software documentation in general.

TECHNICAL SPECIFICATIONS (GOST 19.201-78)

1. General provisions

STAGES OF DEVELOPMENT (GOST 19.102-77)

DESCRIPTION OF THE PROGRAM (GOST 19.402-78)

PROGRAM TEXT (GOST 19.401-78)

PROGRAM AND TEST METHODOLOGY (GOST 19.301-79)

REQUIREMENTS FOR PRINTED SOFTWARE DOCUMENTS (GOST 19.106-78)

Standardization in the field of software documentation

How to move forward

Preparation of documentation for software (PS) in accordance with existing GOSTs

2. General characteristics of the condition

2.3. State standards of the Russian Federation (GOST R)

2.4. International standard ISO/IEC 12207: 1995-08-01

Perhaps the most unpleasant and difficult stage of programming work is the creation of program documentation. Unfortunately, usually this is either not taught at all, or, at best, they do not pay due attention to the quality of the documents received. However, mastery of this art is often one of the most important factors determining the quality of a programmer.

Firstly, the ability to create program documentation determines the professional level of the programmer. The customer will not delve into the intricacies and features of even the most wonderful program. The customer will read the documentation first. The psychological factor also plays a big role in this. In particular, the former Soviet school of programming was (and is now) valued all over the world. Modern domestic programmers have ceased to be quoted. The class is not the same. Nowadays, programs are no longer written, but compiled (and these are “two big differences”). So, a software documentation package (hereinafter referred to as PD) created in the “classical” style will create the most favorable impression on your customer or employer. Moreover, if the author of the PD avoids phrases like “click on the scrollbar...”, “screw”, etc. Unfortunately, such slangy chatter usually hides either a paucity of thoughts or complete emptiness (the author was indelibly impressed by the story of one of his acquaintances about a certain “gamer” who either “chatted” with someone or was engaged in “moderating” or something like that.). The language of PD is a kind of bureaucratic, very conservative language. It has its own special charm. Agree that the terms HDD, HDD, hand-held manipulator such as “mouse” (or “kolobok”, as it was written in one of the old PD packages) sound completely different than the corresponding “screw”, “flop” and simply “mouse”. By the way, things have already reached the point that, they say, even a special specialty has appeared - technical writer, i.e. a person who knows how to create software documentation.

Secondly, a well-designed (more precisely, created) PD package will save you from many troubles. In particular, you can get rid of annoying questions and unfounded claims by simply referring the user to the documentation. This concerns, first of all, the most important document - the Terms of Reference. We will talk about this below, but now we can remind you of the multi-million dollar lawsuit against IBM. This lawsuit was brought by one large publishing house, dissatisfied with the quality of the VT and software. IBM won the case. And she won only because she presented the Terms of Reference signed by both parties. This happened a long time ago, back in the 70s, but this does not change the essence of the matter.

And one more thing. It is important to create the first PD package. This will be enough to build all subsequent ones on its basis, using it as a model or template. But this must be done very efficiently. Take your time. Very thorough.

First you need to arm yourself with GOSTs. GOST defines everything. In particular, it includes the Unified System of Program Documentation (USPD) that interests us. Perhaps the most difficult thing is to get the GOST itself. GOST should only be in printed original form. They are sold (at least that was the case before) in special stores. In particular, to acquire standards in the field of documentation, you can contact the following organizations:

• IPK "Publishing Standards", Territorial department of distribution of NTD (store "Standards"), 17961, Moscow, st. Donskaya, 8, tel. 236-50-34, 237-00-02, fax/tel. 236-34-48 (regarding GOST and GOST R).
• VNIIKI Gosstandart of Russia (reading room), 103001, Moscow, Granatny per. no. 4, tel. 290-50-94 (regarding international, foreign standards and other scientific and technical documentation).

And no quotations or secondary sources. GOST is the law. And even more so, no Internet (imagine a court passing a sentence using a printout of the Criminal Code downloaded from some website). Don't trust anyone other than the original. However, the author will then have to resort to quoting the ESPD, thereby abdicating all responsibility.

Let's start with the general provisions about the Unified System of Program Documentation (which are also defined in the corresponding standard GOST 19.001-77).

The unified system of program documentation is a set of state standards that establish interconnected rules for the development, execution and circulation of programs and program documentation.

ESPD standards define general provisions and fundamental standards, rules for the execution of development documentation, rules for the execution of manufacturing documentation, rules for the execution of support documentation, rules for the execution of operational documentation, rules for circulation of program documentation and other standards. The ESPD includes:

• fundamental and organizational and methodological standards;
• standards defining the forms and content of program documents used in data processing;
• standards that ensure automation of the development of program documents.

In general, the list of ESPD documents is very extensive. In particular, it includes the following GOSTs:

• GOST 19.001-77 ESPD. General provisions.
• GOST 19.101-77 ESPD. Types of programs and program documents (reissued in November 1987 with amendments).
• GOST 19.102-77 ESPD. Development stages.
• GOST 19.103-77 ESPD. Designation of programs and program documents.
• GOST 19.104-78 ESPD. Basic inscriptions.
• GOST 19.105-78 ESPD. General requirements for program documents.
• GOST 19.106-78 ESPD. Requirements for printed program documents.
• GOST 19.201-78 ESPD. Technical specifications. Requirements for content and design.
• GOST 19.202-78 ESPD. Specification. Requirements for content and design.
• GOST 19.301-79 ESPD. Test program and methodology.
• GOST 19.401-78 ESPD. Program text. Requirements for content and design.
• GOST 19.402-78 ESPD. Description of the program.
• GOST 19.404-79 ESPD. Explanatory note. Requirements for content and design.
• GOST 19.501-78 ESPD. Form. Requirements for content and design.
• GOST 19.502-78 ESPD. Description of application. Requirements for content and design.
• GOST 19.503-79 ESPD. System Programmer's Guide. Requirements for content and design.
• GOST 19.504-79 ESPD. Programmer's Guide.
• GOST 19.505-79 ESPD. Operator's manual.
• GOST 19.506-79 ESPD. Description of the language.
• GOST 19.508-79 ESPD. Maintenance Manual. Requirements for content and design.
• GOST 19.604-78 ESPD. Rules for making changes to program documents executed in print.
• GOST 19.701-90 ESPD. Schemes of algorithms, programs, data and systems. Conventions and execution rules.
• GOST 19.781-90. Software for information processing systems.

As you can see, the main part of the ESPD complex was developed in the 70s and 80s. Some of these standards are outdated, and they are not without some drawbacks. Firstly, they do not reflect some modern trends in the design of programs and program documentation, and secondly, these standards contain multiple duplication of fragments of program documentation. Nevertheless, for lack of anything better, we have to focus on them.

So, ESPD standards streamline the process of documenting software systems. However, firstly, the composition of software documents provided for by the ESPD standards is not at all as “rigid” as it might seem: the standards allow additional types to be included in the set of documentation for a software system (PS), and, secondly, based on customer requirements, they are acceptable some changes in both the structure and content of established types of PD. Moreover, it can be noted that the ESPD standards (and this applies to all other standards in the field of PS - GOST 34, the ISO/IEC International Standard, etc.) are advisory in nature. The fact is that in accordance with the Law of the Russian Federation “On Standardization”, these standards become mandatory on a contractual basis - i.e. when referring to them in the contract for the development (supply) of the software.

Before we begin to consider the rules for compiling software documentation, it is necessary to make the following remark. It is advisable to preface each document with some introduction. The introduction speaks generally. About relevance, necessity, etc. The Performer’s goal here is to show the significance and necessity of doing this work. The beginning is usually standard: “The numerous systems currently existing... ... opens up real prospects in...”, etc. Quotes from the speeches of various figures are usually inserted here (this is a purely psychological aspect): “... as was said at the last plenum, congress, conference, etc.). You can start with the fact that “... Today, in the era of indigenous social -economic transformations...etc." In general, the main thing here is not to overdo it.

And one more thing. When describing his product, the developer often confuses the concepts of component and complex. These are different types of programs. A component is defined as “a program considered as a single whole that performs a complete function and is used independently or as part of a complex,” and a complex is “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."

According to GOST, this standard (reissued in November 1987) establishes the procedure for constructing and preparing technical specifications for the development of a program or software product for computers, complexes and systems, regardless of their purpose and scope.

You must be extremely careful and careful when creating it, because... Often a skillfully (and competently) drafted technical specification determines the success of the entire work. It is the technical specifications that are agreed upon with the Customer, who usually strives to introduce as many contradictory and inflated requirements as possible. The task of the Executor is, on the contrary, to make his life easier. But after signatures have been placed on both sides, it’s too late to replay anything.

The terms of reference are drawn up on sheets of A4 and/or A3 format, as a rule, without filling out the fields of the sheet. Sheet (page) numbers are placed at the top of the sheet above the text.

To make changes and additions to the technical background at subsequent stages of development of a program or software product, an addition to it is released. Coordination and approval of additions to the technical specifications are carried out in the same manner as established for the technical specifications.

The terms of reference must contain the following sections:

• name and scope of application;
• basis for development;
• purpose of development;
• technical requirements for a program or software product;
• stages and stages of development;
• control and acceptance procedure;
• applications.

Depending on the features of the program or software product, it is possible to clarify the content of sections, introduce new sections, or combine individual ones.

In the section Name and scope indicate the name, a brief description of the scope of application of the program or software product and the object in which the program or software product is used.

In the section Basis for development must be indicated:

• document(s) on the basis of which the development is carried out;
• the organization that approved this document and the date of its approval;
• name and (or) symbol of the development topic.

In relation to the specifics of the educational process, the basis can be an assignment for course design, an order from the institute dated __.__. for N ___., contract __.__. for N ___. , etc.

In the section Purpose of development The functional and operational purpose of the program or software product must be indicated. You can limit yourself here to one or two phrases. The main thing is to clearly define what this program is for.

For example: The program is the core of an automated workstation (AWS) for the developer of continuous linear automatic control systems (ACS), allowing the user to solve problems of analyzing simple models.

Chapter Technical requirements for a program or software product should contain the following subsections:

• requirements for functional characteristics;
• reliability requirements;
• terms of Use;
• requirements for the composition and parameters of technical means;
• requirements for information and software compatibility;
• labeling and packaging requirements;
• requirements for transportation and storage;
• special requirements.

In other words, this is where the specifics begin. Describes what the program should do and what it should look like.

Requirements for functional characteristics. Here the requirements for the composition of the functions performed, the organization of input and output data, timing characteristics, etc. should be indicated.

For example: The program should allow ... to calculate ... to build ... to create ...

Input data: text file with given...

Output data: graphic and text information - results of system analysis...; text files - reports on ... diagnostics of the system state and messages about all errors that have occurred.

Reliability requirements. Requirements for ensuring reliable operation must be specified (ensuring stable operation, monitoring input and output information, recovery time after a failure, etc.).

It’s difficult to “guess” something here. The best case scenario is that your program only works with absolutely correct data. Usually the Customer does not agree to this, but you can try.

For example: The program must work with a given extended matrix of incidents of the graph under study in accordance with the operating algorithm, generate error messages when the initial data is incorrectly specified, and support an interactive mode within the capabilities provided to the user.

Terms of Use. The operating conditions (ambient temperature, relative humidity, etc. for selected types of storage media) under which the specified characteristics must be ensured, as well as the type of service, the required number and qualifications of personnel must be indicated.

There are usually no difficulties with this point. Unfortunately, the clause about the professionalism of the user by the Customer is necessarily implied. This, of course, is another reason to find fault with your program. However, here we can limit ourselves to phrases like “The operating conditions of the program coincide with the operating conditions of the IBM PC and PCs compatible with them,” “The program should be designed for a non-professional user.” etc.

Requirements for the composition and parameters of technical means. Indicate the required composition of technical means with an indication of their technical characteristics.

The main thing here is not to forget anything and to provide for everything, on the one hand (otherwise they will slip in some kind of IBM PC/XT with a monochrome display and without a mouse), and on the other hand, not to overdo it with increased requirements, otherwise the Customer will find a more flexible Contractor.

For example: You must have an IBM PC - compatible PC with an EGA (VGA) graphics adapter. The required disk space is at least 600 KB, the amount of free RAM is at least 400 KB. It is desirable to have an EMS driver and a mouse-type manipulator.

Requirements for information and software compatibility. The features are the same as in the previous paragraph. Here the requirements for information structures at the input and output and solution methods, source codes, and programming languages ​​should be specified. Where necessary, protection of information and programs must be ensured.

For example: The program must work autonomously under MS DOS OS version no lower than 3.3. The basic programming language is Turbo Pascal 6.0.

Labeling and packaging requirements and transportation and storage requirements are quite exotic. In general, the requirements for labeling a software product, packaging options and methods are indicated here. And the requirements for transportation and storage must indicate for the software product transportation conditions, storage locations, storage conditions, storage conditions, storage periods in various conditions.

Special requirements are a very important thing. It is better to avoid them if possible. And declare it right away.

For example: There are no special requirements for the timing characteristics of the program. There are no special requirements for the capacitive characteristics of the program.

Technical and economic indicators. This most difficult point for a programmer is not always there. It is needed primarily when your goal is to justify the enormous effectiveness and importance of the work being performed. This item usually works very well for the Customer. At the very least, this is the best justification for the timing and monetary amounts of development.

This section should indicate: estimated economic efficiency, estimated annual need (for example: the expected number of calls to the complex as a whole per year - 365 work sessions), economic advantages of the development in comparison with the best domestic and foreign samples or analogues.

In addition, it is advisable to provide a definition of both the estimated cost of program development and a definition of the complexity of programming.

Stages and stages of development(this will be discussed in more detail below) establish the necessary stages of development, stages and content of work (a list of program documents that must be developed, agreed upon and approved), as well as, as a rule, development deadlines and determine the performers.

The standard steps are described here. The main thing is to correctly determine the timing. If possible, try to evenly distribute the stages across deadlines (and amounts). Remember that not all projects make it to the final stage. And there should be reports for each stage. Remember also that the work project will take the most time. If you fail to complete the documentation on time, the Customer has every right not to accept the work at all with all the ensuing consequences.

The main and indispensable stages and phases are the terms of reference itself, the preliminary design, technical and working designs.

• Draft design. At this stage, the structures of input and output data are developed in detail, and the form of their presentation is determined. A general description of the algorithm, the algorithm itself, and the structure of the program are being developed. An action plan for the development and implementation of the program is being developed.
• Technical project. Contains a developed algorithm for solving the problem as well as methods for monitoring initial information. Here, tools for processing errors and issuing diagnostic messages are developed, forms for presenting initial data and the configuration of technical means are determined.
• Working draft. At this stage, programming and debugging of the program, development of program documents, programs and test methods are carried out. Test and debugging examples are being prepared. Documentation and graphic material are finalized. It is usually specified that during program development the following documentation should be prepared:

• program text;
• program description;
• test program and methodology;
• description of application;
• user manual.

These are standard requirements. If the Customer agrees that not all of this list can be presented, then this means that his intentions regarding you and your product are not serious.

There may not be any graphic material. Especially when you are not going to report the results of your work. But for serious projects this item is required.

For example: During the development of the program, the following graphic material should be prepared:

• technical and economic indicators;
• program structure;
• format for presenting program input data;
• general algorithm diagram (2 sheets);
• basic computational algorithms;
• example of how the program works.

In the section Control and acceptance procedure the types of tests and general requirements for acceptance of work must be indicated. If possible, then in this paragraph indicate that “control and acceptance of the development is carried out using equipment provided by the Customer,” otherwise you may be required to bring the equipment with you.

For example: Control and acceptance of development are carried out on the basis of testing test and debugging examples. This checks the execution of all program functions.

IN Applications If necessary, the technical specifications are provided by:

• a list of research and other works justifying the development;
• algorithm diagrams, tables, descriptions, justifications, calculations and other documents that can be used during development;

• other development sources.

This standard establishes the stages of development of programs, program documentation, as well as the stages and content of work:

Notes:

1. It is allowed to exclude the second stage of development, and in technically justified cases - the second and third stages. The need for these stages is indicated in the technical specifications.
2. It is allowed to combine, exclude stages of work and (or) their content, as well as introduce other stages of work as agreed with the customer.

This standard is focused on documenting the resulting development product.

Strictly speaking, there are two different documents, which, however, have much in common. This is a GENERAL DESCRIPTION (GOST 19.502-78) and a DESCRIPTION OF THE PROGRAM (GOST 19.402-78). However, due to the fact that it is very difficult to actually create both of them with high quality, without resorting to almost complete duplication and tearing out pieces, it would be enough to implement one, more general, “hybrid” document. Let's call it "Program Description".

In fact, the “Program Description” in its content can be supplemented by sections and paragraphs taken from the standards for other descriptive documents and manuals: GOST 19.404-79 ESPD. Explanatory note, GOST 19.503-79 ESPD. System Programmer's Guide, GOST 19.504-79 ESPD. Programmer's Guide, GOST 19.505-79 ESPD. Operator's manual, etc. In particular, from the Explanatory Note you can take a diagram of the algorithm, a general description of the algorithm and (or) the functioning of the program, as well as the rationale for the adopted technical and technical-economic decisions.

The description of the program must include an information part - annotation and content.

The main part of the document should consist of an introductory part and the following sections:

• functional purpose;
• description of logic.
• conditions of use;
• composition and functions.

Depending on the specifics of the program, additional sections may be introduced.

IN Introductory part The document provides general information about the program - full name, designation, its possible applications, etc.

For example: The program "Automated workstation for self-propelled guns developer" is intended for... implemented on.... The program supports...

In the section Purpose indicate the purpose of the program and provide a general description of the functioning of the program, its main characteristics, information about the restrictions imposed on the scope of the program, and also indicate the types of electronic computers and devices that are used during operation.

For example: The program is designed to solve problems... The program represents the core of an automated workstation...

The user has the opportunity to..., implement..., run..., analyze..., obtain results of analysis and processing..., build..., etc.

In the section " Description of logic" indicate:

• description of the program structure and its main parts

(for example: The program includes the following:

• user interface,
• module for determining paths in a graph,
• transfer function calculation module,
• module for constructing amplitude and phase frequency characteristics,
• module for constructing a response to a polynomial influence,
• text editor).

• description of the functions of the components and connections between them;

For example: The program consists of six modules: interface module; definition module...; calculation module...; module...etc..

The interface module is built on two types of dialogues: a “question-answer” dialogue and a “menu” type dialogue. The interface module controls...

Definition module... It is...

Calculation module...etc.

• information about the programming language;

For example: The program is written in the language ... using a compiler ...

• description of input and output data for each of the components;

For example: INPUT DATA. The input data for the program is a text file describing the extended incidence matrix of the graph of the system under study.

OUTPUT. The output is:

• graphic and text information displayed on the screen (system analysis results);
• files in one of the graphic formats - copies of the image of the constructed characteristics (AFC, PFC, etc.);
• text files - reports on research conducted;
• diagnostics of the system state and messages about all errors that occur.

• description of the logic of the component parts (if necessary, a description of program diagrams should be written).

When describing the program logic, a link to the program text is necessary.

In the section Composition and functions indicate a description of the composition and function of programs and the methods used to solve problems.

In the section Conditions of use the conditions necessary for the implementation of the program are indicated (requirements for the technical means necessary for this program and other programs, general characteristics of input and output information, as well as requirements and conditions of an organizational, technical and technological nature, etc.).

For example: The program is operated on a personal computer (PC) of the IBM PC/AT type. To work in interactive mode, a display screen, keyboard and mouse are used. To support graphics mode, an EGA (VGA) adapter is required. Input data is stored on floppy and/or hard disks. The program runs under the OS...

The annex to the description may include reference materials (illustrations, tables, graphs, examples, etc.)

And do not forget to indicate the name of the loading module, as well as a description of the entire procedure

Calling and booting the system

The requirements for the design of program text are quite simple and natural for a competent programmer. The main thing to be guided by when creating this document is that the program text should be readable.

It is still mandatory to compile the information part - annotations and contents.

The main part of the document should consist of the texts of one or more sections, which are given names.

The text of each program file begins with a “header”, which indicates:

• name of the program,
• author,
• date of creation of the program,
• version number,
• date of last modification.

Comments are required, as well as strict adherence to indentation rules. Remember, even the inability to create software documentation can be justified. But ugly program text - never. References to the fact that this text is understandable to the author himself are not taken seriously. There should be no shame in giving program texts to other people to read.

Below is an example of such a well-readable program text (taken from Nikolai Gekht’s website, e-mail: [email protected], http://users.omskreg.ru/~geht)

/* Windows 98 sources

Source Code to Windows 98 */ #include "win31.h" #include "win95.h" #include "evenmore.h" #include "oldstuff.h" #include "billrulz.h" #include "monopoly.h" # define INSTALL = HARD char make_prog_look_big; void main() ( while(!CRASHED) ( display_copyright_message(); display_bill_rules_message(); do_nothing_loop(); if(first_time_installation) ( make_50_megabyte_swapfile(); do_nothing_loop(); totally_screw_up_HPFS_file_system(); search_and_destroy_the_rest_of_OS/2(); disable_Netscape(); disable_RealPlayer(); disable_Corel_Products(); write_something(anything); do_nothing_loop(); if(still_not_crashed) (display_copyright_message(); basically_run_windows_3.1(); (); do_nothing_loop(); ) ) if(detect_cache()) disable_cache(); if(fast_cpu()) ( set_wait_states(lots); set_mouse(speed, very_slow); set_mouse(action, jumpy); set_mouse(reaction, sometimes ); ) /* printf("Welcome to Windows 3.11"); */ /* printf("Welcome to Windows 95"); ) else system_memory = open("a:\swp0001.swp", O_CREATE); while(something) ( sleep(5); get_user_input(); sleep(5); act_on_user_input(); sleep(5); ) create_general_protection_fault();

This document contains a description of what and how needs to be done in order to make sure (and convince the Customer) that the program is working correctly. In fact, this document is decisive for acceptance tests. A well-designed test program and methodology is the key to signing the acceptance certificate, i.e. the thing for which you spent so much time and effort.

Formally, this GOST is used to develop planning documents and conduct test work to assess the readiness and quality of the software system. The document contains a description of the object and purpose of testing, requirements for the program and software documentation, means and procedure for testing, as well as a description of test examples.

The components of this document are easier and more clearly described in the form of examples.

Test object

Example: The test object is the program ..., intended for ...

Purpose of testing

Example: Checking the reliability of the program.

Program requirements

Example: The operation of the program should not lead to a failure (fatal disruption of the system). The organization of the dialogue should provide protection against entering incorrect data. The program should provide diagnostics of the system state and messages about any errors that have occurred... etc.

Requirements for software documentation

Example: Contents of software documentation presented during testing:

• description of the program (GOST 19.402-78);
• test program and methodology (GOST 19.301-79);
• text of the program (GOST 19.401-78).

Test means and procedure

Example: The program operates in accordance with the operating conditions of MS DOS OS (version no lower than 3.0) on PCs of the IBM PC/AT type, as well as on those compatible with it. An EGA (VGA) adapter is also required for operation.

Test procedure:

1. The program is launched….
2. Selected...
3. Pressed...
4. Sequentially selected...

Test cases

Example: For testing, ... are proposed, the descriptions of which are contained in the files ... The contents of the test files and the results of the program are given in Appendix 1.

And finally, let's look at the latest ESPD standard, which is called

This standard establishes rules for the execution of program documents for computers, complexes and systems, regardless of their purpose and scope of application and provided for by ESPD standards.

General requirements. It is necessary to enter individual words, formulas, symbols (by hand in a drawing font), letters of the Latin and Greek alphabets, as well as to draw diagrams and drawings in program documents made by typewriting, machine and handwriting, in black ink or ink.

Typos and graphic inaccuracies discovered during the execution process can be corrected by erasing a poorly executed part of the text (drawing) and applying the corrected text (graphics) on the same sheet in typescript or black ink, depending on the method of execution of the document.

Damage to document sheets, blots and traces of incompletely deleted text (graphics) are not allowed.

Program documents are drawn up on A4 sheets. Besides:

• It is acceptable to print on A3 sheets;
• with the machine method of document execution, deviations in the size of sheets corresponding to A4 and A3 formats are allowed, determined by the capabilities of the technical means used; on sheets of A4 and A3 formats, provided for by the output characteristics of data output devices, when producing a document by machine;
• When producing a document using a typographic method, it is possible to use sheets of typographic formats.

The materials of the program document are arranged 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.);
• list of terms and their definitions;
• list of abbreviations;
• applications;
• subject index;
• list of reference documents;

• change logging part:

• change registration sheet.

Construction of the document. If necessary, it is allowed to divide the document into parts. Division into parts is carried out at a level not lower than the section. Each part is completed separately, and at the end of the contents of the first part the names of the remaining parts should be listed.

It is allowed to include in the document parts of the program text, formatted in accordance with the rules of the language in which the program text is written.

The annotation is placed on a separate page (pages), provided with the heading "ABSTRACT", numbered and included in the contents of the document.

The text of each document, if necessary, is divided into paragraphs, and paragraphs into subparagraphs, regardless of whether the document is divided into parts, sections and subsections or not.

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. It is recommended to start each section on a new sheet.

Sections, subsections, paragraphs and subparagraphs should be numbered in Arabic numerals with a dot. Sections must have a serial number (1, 2, etc.)

Document text. 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.

If a footnote refers to a single word, the footnote sign is placed directly next to this word, but if it refers to a 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. Illustrations can be located in the text of the document and (or) in appendices. Illustrations, if there is more than one of them in a given document, are numbered in Arabic numerals throughout the entire document.

In appendices, illustrations are numbered within each appendix in the order established for the main text of the document. References to illustrations are given by type: “Fig. 12” or “(Fig. 12)”. Illustrations may have a thematic title and caption text explaining the content of the illustration.

Formulas. 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. Within the entire document or its parts, if the document is divided into parts, the formulas have continuous numbering.

References in the text to the serial number of the formula are given in parentheses, for example: “in formula (3)”. When dividing a document into parts, the part number is placed before the serial number of the formula and is separated from the last dot, for example: “in formula (1.4)”.

The meaning of the symbols 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.

Links. References to standards and other documents are permitted in policy documents. 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).

It is allowed to indicate only the designation of the document and (or) sections without indicating their names. References to individual subsections, paragraphs and illustrations of another document are not allowed. Links within the document to paragraphs, illustrations and individual subsections are allowed.

Notes 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. The text of notes may be printed only at one interval.

Abbreviations. Abbreviations of words in the text and inscriptions under illustrations are not allowed, with the exception of:

• abbreviations established in GOST 2.316-68 and generally accepted in the Russian language;
• abbreviations used to designate programs, their parts and operating modes, in task control languages, in program configuration tools, etc., denoted by letters of the Latin alphabet.

Applications. Illustrated material, tables or supporting text may be presented in the form of appendices. Applications are drawn up as a continuation of this document on subsequent pages or issued as a separate document.

Each application must begin on a new page with the word "Application" in the upper right corner and have a topical heading. If there is more than one attachment in a document, all attachments are numbered in Arabic numerals (without the No. sign), for example:

Appendix 1, Appendix 2, etc.

When issuing an application as a separate document, the word “Appendix” should be indicated on the title page under the name of the document, and if there are several applications, its serial number should also be indicated.

Preparation of program documentation

Technical specifications for the development of a software product

3.2. Description of the program

3.3. Program text

Test program and methodology

3.5. Requirements for printed program documents

Application. Form of technical specifications for the development of a software product (product, model)

Introduction. General information about the Unified System of Program Documentation (USPD).

The unified system of program documentation is a set of state standards that establish interconnected rules for the development, execution and circulation of programs and program documentation.

ESPD standards define general provisions and fundamental standards, rules for the execution of development documentation, rules for the execution of manufacturing documentation, rules for the execution of support documentation, rules for the execution of operational documentation, rules for circulation of program documentation and other standards.

The ESPD includes:

· fundamental and organizational and methodological standards;

· standards defining the forms and content of program documents used in data processing;

· standards that ensure automation of the development of program documents.

The list of ESPD documents includes the following GOSTs:

GOST 19.001-77 ESPD. General provisions.

GOST 19.101-77 ESPD. Types of programs and program documents (reissued in November 1987 with amendments).

GOST 19.102-77 ESPD. Development stages.

GOST 19.103-77 ESPD. Designation of programs and program documents.

GOST 19.104-78 ESPD. Basic inscriptions.

GOST 19.105-78 ESPD. General requirements for program documents.

GOST 19.106-78 ESPD. Requirements for printed program documents.

GOST 19.201-78 ESPD. Technical specifications. Requirements for content and design.

GOST 19.202-78 ESPD. Specification. Requirements for content and design.

GOST 19.301-79 ESPD. Test program and methodology.

GOST 19.401-78 ESPD. Program text. Requirements for content and design.

GOST 19.402-78 ESPD. Description of the program.

GOST 19.404-79 ESPD. Explanatory note. Requirements for content and design.

GOST 19.501-78 ESPD. Form. Requirements for content and design.

GOST 19.502-78 ESPD. Description of application. Requirements for content and design.

GOST 19.503-79 ESPD. System Programmer's Guide. Requirements for content and design.

GOST 19.504-79 ESPD. Programmer's Guide.

GOST 19.505-79 ESPD. Operator's manual.

GOST 19.506-79 ESPD. Description of the language.

GOST 19.508-79 ESPD. Maintenance Manual. Requirements for content and design.

GOST 19.604-78 ESPD. Rules for making changes to program documents executed in print.

GOST 19.701-90 ESPD. Schemes of algorithms, programs, data and systems. Conventions and execution rules.

GOST 19.781-90. Software for information processing systems.

Other standards in the field of documenting software systems (PS) include:

GOST 34.602-89 Information technology. A set of standards for automated systems. Terms of reference for the creation of an automated system.

GOST 34.601-90 Information technology. A set of standards for automated systems. Automated system. Stages of creation.

GOST R ISO/IEC TO 12182-2002 Information technology. Classification of software.

GOST R ISO/IEC 12207-99 Information technology. Software life cycle processes.

GOST R ISO/IEC 14764-2002 Information technology. Maintenance of software.

GOST R ISO/IEC 15026-2002 Information technology. Levels of integrity of systems and software.

GOST R ISO/IEC TO 15271-2002 Information technology. Guidelines for the application of GOST R ISO/IEC 12207-99.

GOST R ISO/IEC 15910-2002 Information technology. The process of creating software user documentation.

ISO/IEC International Standards:

ISO/IEC 12207:2008 System and software engineering – Software life cycle processes.

ISO/IEC 15288:2008 System and software engineering – System life cycle processes.

IEEE 830-1998 Recommended practice for software requirements specifications.

IEEE 1233-1998 Guide for developing system requirements specifications.

IEEE 1016-1998 Recommended Practice for Software Design Descriptions.

ISO/IEC 42010 IEEE Std 1471-2000 System and software engineering – Recommended practice for architectural description of software-intensive systems.

ISO 9001:2000 Quality management systems – Requirements.

ISO/IEC 90003:2004 Software engineering – Guidelines for the application of ISO 9001:2000 to computer software.

ISO/IEC TR 90005:2008 Software engineering – Guidelines for the application of ISO 9001:2000 to system life cycle processes.

ISO/IEC 9126-1:2001 Software engineering – Product quality – Part 1: Quality model.

ISO/IEC 9126-2:2003 Software engineering – Product quality – Part 2: External metrics.

ISO/IEC 9126-3:2003 Software engineering – Product quality – Part 3: Internal metrics.

ISO/IEC 9126-4:2004 Software engineering – Product quality – Part 4: Quality in use metrics.

ISO/IEC 25051:2006 Software engineering – Software product Quality Requirements and Evaluation (SQuaRE) – Requirements for quality of Commercial Off-The-Shelf (COTS) software product and instructions for testing.

IEEE 829-1998 Standard for Software Test Documentation.

IEEE 829-2008 Standard for Software and System Test Documentation.

IEEE 1008-1987 (R1993, R2002) Standard for Software Unit Testing.

ISO/IEC 14598-1:1999 Information technology – Software product evaluation – Part 1: General overview.

ISO/IEC 14598-2:2000 Software engineering – Product evaluation – Part 2: Planning and management.

ISO/IEC 14598-3:2000 Software engineering – Product evaluation – Part 3: Process for developers.

ISO/IEC 14598-4:1999 Software engineering – Product evaluation – Part 4: Process for acquirers.

ISO/IEC 14598-5:1998 Information technology – Software product evaluation – Part 5: Process for evaluators.

ISO/IEC 14598-6:2001 Software engineering – Product evaluation – Part 6: Documentation of evaluation modules.

As you can see, the main part of the set of domestic ESPD standards was developed in the 70s and 80s. Some of these standards are morally outdated, and they are not without some shortcomings: firstly, they do not reflect some modern trends in the design of programs and program documentation, and secondly, in these standards there is multiple duplication of fragments of program documentation. Nevertheless, for lack of anything better, we have to focus on them.

ESPD standards streamline the process of documenting software systems. At the same time, ESPD standards, based on the Customer’s requirements, allow some changes to be made to the set of documentation for software systems, both in the structure and content of the established types of software documents.

In addition, the standards listed above are advisory in nature and become mandatory on a contractual basis - i.e. when referring to them in an agreement for the development or supply of software.

When considering the rules for compiling program documentation, it is necessary to keep in mind that it is advisable to preface each document with some introduction.

The introduction contains general words about relevance, necessity and significance, etc. developed software product.