Experience with ESPD

Introduction


The main task of this text is to tell you what the Unified Program Documentation System (UPRP) is and how to apply these standards in practice. I will start with a talk about what standards exist and end with the experience of applying each of the CESD standards individually.

At one time, when I was just starting to work as a programmer, I often heard “write, please, the documentation for your program”. I honestly described everything, gave it to the boss, after which the session of black magic began. After some time, the boss called me up and started mumbling inarticulate sounds, wrinkling the printout of my “best” text in his hands, running his eyes. The general meaning of his lowing was that it turned out “wrong”, “wrong”, and “look at how others do it.” Since it was impossible to get any other answer out of it, I went for examples of documents to “others”. As a rule, these were funny guys, the meaning of the speeches was that “here are examples”, “in general, according to GOST” and “nobody needs all this”. So I learned for the first time that a programmer can come into contact with the terrible GOSTs.
It is amazing that among many dozens of my colleagues, very stupid programmers, there was no one who would treat GOSTs differently. Even those few people who knew them and, seemingly, even knew how to draw up documents, treated them scornfully formally. The situation where even the people responsible for managing the development do not understand why GOSTs are needed and how they are applied is found in many enterprises all the time. Yes, there were companies in which they understood how the “Description of the program” differs from the “Description of the application”, but there were a clear minority. The Internet is generally dominated by the point of view that GOSTs for programmers are a clear vestige, and are needed only if they “bend” under them. The draft design is considered “a relatively honest way of weaning extra money from the customer.” I had to delve into and sort it out relatively recently - in the process of developing a requirements management system sharpened for domestic specifics. Documentation which, of course, should generate “in accordance with GOST”.

Here I want to focus on only one topic that a programmer has to deal with in domestic enterprises, especially in a research institute - on a set of ESPD standards. I do not consider myself a great connoisseur of the Unified Road Transport Policy - there are people who have worked on it for decades, and they will surely correct me. The article is rather trying to outline the contours of the “road map” for those who are just getting into the picture.

Standards


Let's take a brief look at what standards exist (focusing on IT).
  1. international. Distinctive feature - adopted by an international organization. An example of such an organization is ISO (International Organization for Standardization). An example of its standard is: ISO 2382-12: 1988 (Peripheral equipment). Joint standards of ISO and the International Electrotechnical Commission (IEC, in Russian - IEC) are common: for example, ISO / IEC 12207: 2008 (software life cycle);
  2. regional. Distinctive feature - adopted by the regional standardization commission. For example, many Soviet GOSTs are now a regional standard, because adopted by the interstate council, which includes some of the former Soviet republics. With this advice, new standards are adopted - and they also receive the GOST designation. Example: GOST 12.4.240-2013;
  3. standards of public associations; For example, the same IEC: IEC 60255;
  4. national standards. For Russia, at the beginning of such standards is “GOST R”. There can be three types:
    1. exact copies of international or regional. Indicated indistinguishable from “self-written” (national, written independently);
    2. copies of international or regional with additions. They are indicated by adding to the cipher the domestic standard of the international cipher, which was taken as a basis. For example: GOST R ISO / IEC 12207;
    3. Actually, national standards. For example, GOST R 34.11-94.



The notation systems at each level and in each organization are different, for each case it will be necessary to understand separately. To quickly understand whose whose standard is before your eyes, you can use a cheat sheet .

GOST


So: the standards are international, interstate (regional) and national. GOST, as we found out, is a regional standard. GOSTs have a rather complicated, in my opinion, notation. It is fully set forth in GOST R 1.5-2004, I will give a minimum to navigate it. Firstly, it is necessary to distinguish the designation of GOST and its classification. A designation is, roughly speaking, a unique identifier for a standard. Classifier code is an auxiliary code that helps you find a standard or determine which area of ​​expertise it belongs to. There can be many classifiers, mainly two are used: KGS (classifier of state standards) and its successor ACS (all-Russian classifier of standards). For example: “GOST R 50628-2000“ is the designation of the standard. The designation only understands that it was adopted in 2000. It has a code for ACS “33.100; 35.160”: i.e. “33” - section “Telecommunications, audio, video”, “100” - subsection “electromagnetic compatibility”. However, it also belongs to the classifier 35.160 branch. “35” - “Information technology. Office machines ”,“ 160 ”-“ Microprocessor systems .... ”. And according to the CGS, it has the code “E02”, which means “E” - “Electronic Engineering, Electronics and Communications”, “0” - “General Rules and Norms on Electronic Engineering, Electronics and Communications”, etc.

If the designation of the standard is known, then you can get its codes for CGS and ACS, for example, on this sensible site .
So, back to the designations of GOSTs. There can be two options:
  1. standard refers to a series of standards. In this case, after the index of the category of the standard (for example, GOST, GOST R or GOST RV), there is a series code, a dot and a designation of the standard inside 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;
  2. standard does not apply to a series of standards. Then after the index of the category is simply the serial number of the standard, a dash and the year of adoption. For example, GOST R 50628-2000.

So, if it’s quite simple - then the GOST designation is either just an ordinal number, a dash, a year, or a series number, a point and further depending on the series. In reality, everything is more complicated (for example, you can meet something like GOST 11326.19-79, and this will not be 11326 series at all - but programmers need this very rarely. For details, see GOST R 1.5-2004).

ESPD


ESPD is one of such series of GOSTs, number 19. I.e. All standards related to the Unified Road Transport Regulation begin with the prefix “19.”: for example, GOST 19.106-78. It stands for “Unified software documentation system”. There are other series:
  • GOST ESKD (unified system for design documentation, prefix “2.”);
  • GOST ESTD (unified system of technological documentation, prefix “3.”);
  • GOST R, System for the development and putting products into production, prefix “15.”;
  • GOST RV, Armament and military equipment. The system of development and putting products into production, the prefix “15.”;
  • GOST, System of technical documentation for ACS, prefix “24.”;
  • GOST, A set of standards for automated systems, the prefix “34.”.

So, ESPD contains a set of standards used in software development. Further, for each standard from the Unified Framework of Regulation on Business, a brief description and explanation is given for non-obvious cases.

19.001-77. General Provisions

Describes the rules for the assignment of designation standards in the ESPD series. In practical life is not needed.

19.102-80. Schemes of algorithms and programs. Rules of execution.

Describes the rules for constructing and designing algorithms. Uses the notation of 19.103. In my practice, the only time I needed was when the certification laboratory rested on a formal basis that the algorithm scheme was needed. From my point of view, the classic two-legged flowcharts are in the past, and the only thing where they remained more or less appropriate is if the author wants to focus the reader’s attention on the algorithm in the presentation.

19.003-80. Schemes of algorithms and programs. Graphic Conventions

The graphic designations of the allowed types of elements of the flowchart are given. Useful if flowcharts are used.

19.004-80. Terms and Definitions.

Scanty Glossary. From interesting - contains formal definitions of program and operational documents.

19.005-85. P-schemes of algorithms and programs

Almost forgotten language. At one time, P-circuits were widely used in the rocket and space industry, becoming the de facto standard for writing launch control programs and launch simulations. However, now this language is completely oblivious. In my work, I have never encountered P-circuits. Although they have significant advantages over block diagrams: they are compact, suitable for visualizing non-linear algorithms (for example, classes in C ++) or data structures. At the same time, there is practically no information on them on the Internet: this and this sites seemed to me useful . In any case, if now I had to insert the algorithm diagram into the program documentation, I would choose P-schemes, and not block-schemes.

19.101-77. Types of programs and program documents

It contains a table of correspondence of the type of document to its code, as well as the division of types of documents into operational and software. The concept of complex and component is introduced. There is nothing more useful.

19.102-77. Development stages

An important and necessary standard, which describes the types of documents and gives codes of 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), a separation is given: which documents are operational, which are not.
You should carefully refer to table 4, which shows which document at what stage of development is carried out. The development stages are usually regulated in the standards for the implementation of design and development work, and it also indicates what documents should be presented to the customer at each stage.

19.102-77. Development stages

In my memory, this standard has never been applied: who does what at what stage and what reports it is written in the TTZ or reference is made to GOSTs, where it is spelled out more clearly (for example, GOST RV 15.203). At the same time, for a beginner, he contains a good synopsis of work at the main stages of OCD in its conciseness.

19.103-77. Designations of programs and program documents

It is needed mainly in order to learn how to read the designations of documents like the one above. However, understanding the notation scheme is useful when you have to go beyond the scope of standard work: for example, remember that documents with codes after 90 are user-defined, i.e. any. In my practice, we issued document 93, which was called “Statement of program documentation”, 96 document - “Assembly instructions”.
The common phrase “execution option” is absent in the Unified Road Transport System, and is replaced by the “revision number”. On the one hand, this is not entirely correct: the editorial number was conceived to track the evolution of the program: first, the first edition comes out, then, for example, after refinement, the second. But in practice, when you need to release a software version for several operating systems (cross-platform software), there is no other way. More precisely, there is, but it’s wrong: assign a version for each OS, its own designation, and put several disks with source codes in the archive (according to the number of OSes), develop (actually copy) the entire set of documentation, etc. ... Ie sheer stupid and confusing activity. The decision in the form of assigning a version for each OS of its own revision number allows you to make some of the documents common.
The ESPD uses the embarrassment of many programmers to denote the source code of a program and the assembly result by “documents”. The document “program text”, according to 19.101-77, has the designation 12. It is further assumed that the source code is designated as 12 01 - i.e. 01 (first) document of type 12, and binaries - as 12 02 - i.e. the second document is of type 12. In some cases, additional tools are needed to build the program — compilers, installer generators, etc. Those. programs that are not included in the delivery, but are needed for assembly. The solution could be to designate them as 12 03 - i.e. a third document of type 12.

19.104-78. Main inscriptions

Describes two sheets of a document - an approval sheet (LU) and a title page. The approval sheet in the ESPD contains the signatures of both the authorities who approved the document, as well as developers, normative controllers, representatives of acceptance, etc. Those. it contains quite a lot of sensitive information for the enterprise. Therefore, it is accepted in the standard that the control unit remains at the development company, and is sent only by special instruction. Once again - LU is not part of the document, but is, as it were, a separate document, and it is entered on a separate line in the specification.
At first, the embarrassing oddity in separating LU from the document itself has very good reasons:
  • As already mentioned, often the company does not want to disclose information about the developer. The LU separation and its “squeezing” allows this to be done (unlike ESKD, there is no stamp in the ESPD on the sheets of the document, all information is localized only in the LU);
  • at a number of enterprises mixed document management is used: the original documents are stored in electronic form in the archive of the enterprise, and LU on them (with original signatures) - in paper;

As for the design of the LU, the mixes are used very often at the enterprises - some of the inscriptions of LU are drawn up according to the Unified State Standard, partly according to ESKD, and partly according to their own. Therefore, it is best, before doing the LU yourself, to look for an enterprise standard (STO), or to take an example from local normative control.
It should also be remembered that the LU is not numbered, and the first sheet is the title page, and the first sheet on which the number is placed is the next after the title page. But in the event that the LU is more than one (this happens if all the signatures have not fit on the sheet), then the LU are numbered separately.

19.105-78. General requirements for program documents

The general structure of the document is introduced, independent of the way it is executed. Those. back in 1978 it was laid down in the standard that a document may not be necessarily paper. In particular, the concept of content is introduced for fully electronic documents. For paperwork, common at that time, GOST 19.106-78 was adopted.
Currently, this standard has to be accessed very rarely: unless the order of the main parts of the document is forgotten.

19.106-78. General requirements for printed program documents

The most voluminous standard of the ESPD, inferior only to the description of R-schemes. It is the main working standard in the preparation of documentation. Introduces the rules for the design of text, elements of the structure of the document, images, formulas, etc. However, unlike the corresponding 2.106 from ESKD, 19.106 is significantly less detailed, which leads to numerous uncertainties.
First, the standard does not actually define line spacing and the amount of vertical indentation between the headers. He introduces three rules for determining the interval: for typewritten text, machine and typographic.
Typewritten text is typewritten text. The shift of the next line relative to the previous one was carried out automatically with the so-called “carriage transfer” - the transition to printing the next line by moving a special lever. As a rule, the interval could be manually adjusted by turning the paper feed shaft, and had a “setting” that allows you to set the interval value - single or double.
Machine - this is most likely the printed text. But for him there is only an indication that the result should be suitable for microfilming. This is an implicit reference to 13.1.002-2003, which, unfortunately, sets the line spacing (and, by the way, the minimum font height) only for handwritten documents (Section 4.2.5).
Typographic - text typed in a print shop. Given the year of adoption of the standard, most likely we are talking about
[ letterpress , where the line spacing was determined by the letters used. I am not a specialist in the printing business, and now there is very little information about the methods of recruitment.
Which interval to use in the end is often determined by local regulatory control or service stations. Typical values ​​are one and a half spacing and 14 font size.
Often there are many questions about how a document is structured. 19.106 believes that the entire document is divided into sections, subsections, paragraphs and subparagraphs. All of them (except for the section and subsection) may or may not have a heading. Wherein:
  • “The contents of the document include the number of sections, subsections, paragraphs and subparagraphs with a heading” (paragraph 2.1.4). This is a direct indication that the subparagraph may have a heading and be included in the table of contents;
  • “It is allowed to place text between the headings of the section and subsection, between the headings of the subsection and paragraph.” It is important to note that unnumbered text can only be between headings, and only at the top 2 levels.

In contrast to the ESKD, the ESPD adopted a strange way to design drawings: first comes the name of the drawing, then the drawing itself, then the optional “figure text”, and then, on a new line, “Fig. N ".
This standard has a number of “holes”, shortcomings. For example, it is said: “illustrations, if there are more than one in this document, are numbered in Arabic numerals within the entire document. “But if the illustration is one, then it is unnumbered, and how then to refer to it? Similarly for tables. For footnotes, GOST does not indicate how to number them — within the entire document or within the page.
Tables. The document itself refers to GOST 1.5.68. Judging by the first series, it is easy to conclude that this is a standard for the development of standards. And here he is, it is unclear. In terms of meaning, it complies with the rules for formatting tables in ESKD, with few exceptions. This standard was canceled, replaced instead, after several iterations, 1.5-2012, in which the rules for table design ... just disappeared. They were still in 1.5-2002, and already in 1.5-2004 they disappeared. In real life, we design tables according to ESKD.
Applications The standard does not indicate whether figures, formulas and tables from the applications fall into the general list. Similarly, it is not said whether the structure of the application should be disclosed in the table of contents if it contains its sections, paragraphs, etc. In our practice, we do not reveal the insides of applications.
Finally, it should be said about the indentation. An indent of 5 characters is common for:
  • red line;
  • the indentation of the document structure element after the section (subsection, paragraph, subparagraph);
  • listing item.

    • In this case, the text located on the next line after the indented line is aligned with the left margin. Often there are errors when the indent jumps - the red line - one value, the item number - us another interval, in nested indents in lists - this is generally necessary.

    In the following parts, I plan to get to the end of the list of standards of the ECPD.
Tags:

Also popular now: