Geekly Articles each Day
📜 ⬆️ ⬇️

Experience of using ESPD

Introduction


The main objective of this text is to tell what the Unified Program Documentation System (ESPD) is and how to apply these standards in practice. I will begin with a story about what standards there are, and end with the experience of applying each of the ESPD standards separately.

When I first started working as a programmer, I often had to hear “please write the documentation for your program”. I honestly described everything, gave it to my boss, after which the black magic session began. After some time, the boss called me and began to moo inarticulate sounds, crushing the printout of my “best” text in my hands, running my eyes. The general meaning of his mooing was that what “wrong”, “wrong”, and “look at how others do.” Since no other answer could be drawn from it, I followed the examples of documents to “others”. As a rule, these were funny guys, the meaning of the speeches of which was that “here are examples”, “generally according to GOST” and “nobody needs it all”. So I found out for the first time that a programmer could come in contact with terrible GOSTs.
It is amazing that among many dozens of my colleagues, very intelligent programmers, there was no one who would treat the guests to another. Even those few people who knew them and, it seemed, even knew how to draw up documents, treated them formally and formally. The situation when even the people responsible for managing the development do not understand why we need GOSTs and how they will be used can be found in many enterprises, very often. Yes, there were also companies in which they understood how the “Program Description” differs from the “Application Description”, but there was a clear minority of such. On the Internet, the point of view prevails in general that GOSTs for programmers are an obvious vestige, and are only needed if they are “bent” for them. The draft design is considered “a relatively fair way to weaning extra bank notes from a customer”. It was necessary to penetrate and figure out relatively recently - in the process of developing a requirements management system, tailored to domestic specifics. Documentation which, of course, should generate "in accordance with GOST".

Here I want to focus only on one topic that the programmer in domestic enterprises has to deal with, especially in scientific research institutes - on the set of ESPD standards. I do not consider myself a great expert on ESPD - there are people who have been working on it for dozens of years, and they probably will correct me. The article rather tries to outline the outlines of the “road map” for those who are just in the know.

Standards


Consider briefly what are the standards (focusing on the IT area).
  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: ISO 2382-12: 1988 (Peripheral equipment). Common 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, since adopted by the Interstate Council, which includes some of the former Soviet republics. New standards are also adopted by this council - and they also receive the designation GOST. 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 - “GOST R”. There may be three types:
    1. exact copies of international or regional. Indicated indistinguishably from the "samopinnyh" (national, written independently);
    2. copies of international or regional supplements. Denoted by adding to the cipher of the national standard cipher international, which was taken as a basis. For example: GOST R ISO / IEC 12207;
    3. Actually, national standards. For example, GOST R 34.11-94.



Notation systems at each level and in each organization have their own, for each case it will be necessary to understand separately. To quickly understand "whose" standard before your eyes, you can use the cheat sheet .
')

GOST


So: standards are international, interstate (regional) and national. GOST, as we found out, is a regional standard. GOSTs have a rather confusing, in my opinion, notation. It is fully set out in GOST R 1.5-2004, I will give a minimum that would be oriented in it. First, it is necessary to distinguish the designation of the GOST and its classification. The designation is, roughly speaking, the unique identifier of the standard. Code by classifier is an auxiliary code that helps to find a standard or determine which field of knowledge it belongs to. There may be a lot of classifiers, two are mainly 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 a standard. According to the designation, it is only clear that it was adopted in 2000. It has an ACS code “33.100; 35.160”: i.e. “33” - section “Telecommunications, audio, video”, “100” - subsection “electromagnetic compatibility”. However, it also enters the classifier branch 35.160. “35” - “Information technology. Office machines ”,“ 160 ”-“ Microprocessor systems .... ”. And according to the CSC, it has the code “E02”, which means “E” - “Electronic equipment, electronics and communications”, “0” - “General rules and regulations for electronic equipment, electronics and communications,” etc.

If the designation of the standard is known, then it can be obtained its codes by CSC and ACS, for example, on this sensible site .
So back to the notation GOST. There may be two options:
  1. The standard is a series of standards. In this case, after the index of the category of the standard (for example, GOST, GOST R or GOST RV) is the code of the series, the point and designation of the standard within the series. The rules for designating standards within a series are established by the rules of the series. For example: GOST RV 15.201-2000, GOST R 22.8.0-99, GOST 19.101-77;
  2. The standard does not belong to a series of standards. Then after the category index is just the ordinal number of the standard, a dash and a year of adoption. For example, GOST R 50628-2000.

So, if it is quite simple - then the designation of a GOST is either just a serial 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 find something like GOST 11326.19-79, and this will not be the 11326 series at all - but programmers need this very rarely. For details, see GOST R 1.5-2004).

ESPD


ESPD is one of such a series of GOST standards, number 19. That is, all standards related to ESPD begin with the prefix “19.”: for example, GOST 19.106-78. It stands for “Unified system of program documentation”. There are other series:
  • GOST ESKD (unified system for design documentation, prefix “2.”);
  • GOST ESTD (unified system of technological documentation, the prefix “3.”);
  • GOST R, System for the development and production of products for production, the prefix “15.”;
  • GOST RV, Armament and military equipment. System development and production of products, the prefix “15.”;
  • GOST, the System of technical documentation for the automated control system, the prefix “24.”;
  • GOST, Automated System Standards Complex, prefix “34.”.

So, ESPD contains a set of standards used in software development. Further, for each standard of ESPD provides a brief description and explanation for non-obvious cases.

19.001-77. General provisions

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

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

Describes the rules for the construction and design of algorithms. Uses notation from 19.103. In my practice, I needed a single time when, at a certification laboratory, I rested on the formal sign that it was the algorithm scheme that was needed. From my point of view, classical flowcharts with two legs in the past, and the only thing where they were left more or less relevant, is if, when presenting, the author wants to focus the attention of the reader on the algorithm.

19.003-80. Schemes of algorithms and programs. Symbols conditional graphic

The graphic symbols of the allowed types of elements of the block diagram are given. Required if flowcharts are used.

19.004-80. Terms and Definitions.

A poor glossary. From the interesting - contains the formal definitions of the program and operational documents.

19.005-85. R-schemes of algorithms and programs

Almost forgotten language. At one time, R-schemes were widely used in the rocket and space industry, becoming the de facto standard for writing launch control programs and launch simulation. However, now this language is completely forgotten. In my work, I have never come across R-diagrams. Although compared with block diagrams, they have significant advantages: 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 useful to me. In any case, if I now had to insert an algorithm diagram in the program documentation, I would choose R-diagrams rather than flowcharts.

19.101-77. Types of programs and program documents

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

19.102-77. Development stages

An important and necessary standard in which the types of documents are described and the codes of the types of program documents are given. This standard (together with 19.103-77) is one of the keys to the “clue” to the notation of documents similar to ABCG.10473-01 32 01-1.
The standard introduces the concept of a complex and a component (in a number of enterprises a third type is added - a set, when it comes to unrelated software elements), a distinction is given: which documents are operational, which are not.
You should be careful about table 4, which shows which document is being executed at what stage of development. The development stages are usually regulated in the standards for the implementation of OCD, and there it is also indicated which documents should be presented to the customer at each stage.

19.102-77. Development stages

In my memory, this standard has not been applied once: who does what at what stage and what reports is prescribed in the TTZ or referred to GOST, where it is spelled out more clearly (for example, GOST RV 15.203). At the same time, for a beginner, he contains a good summary of works in the main stages of OCD.

19.103-77. Designations of programs and program documents

It is mainly needed in order to learn how to read document designations like the one above. However, understanding the notation scheme is useful in the case when you have to go beyond typical work: for example, remember that documents with codes after 90 are custom, that is, any In my practice, we issued document 93, which was called “Statement of program documentation”, 96 document - “Assembly Instructions”.
The common phrase “version of execution” in ESPD is absent, and is replaced by “revision number”. On the one hand, this is not entirely correct: the revision number was conceived to track the evolution of the program: first, the first edition comes out, then, for example, after revision, the second. But in practice, when you need to release a software version for several operating systems (cross-platform software), there is no other way out. More precisely - there is, but wrong: assign the version for each operating system its own designation - and put in the archive several disks with sources (by the number of operating systems), develop (actually copy) the entire set of documentation, etc. ... Ie pure stupid and confusing activity. The solution in the form of assigning a version for each OS of its own revision number allows some documents to be shared.
The ESPD uses the embarrassing designation of the program source code and the result of the assembly “documents” by many programmers. The document “program text”, according to 19.101-77, has the designation 12. Further it is accepted that the source code is designated as 12 01 - i.e. 01 (first) document of type 12, and binaries - like 12 02 - i.e. second document 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 need to build. The solution may be their designation as 12 03 - i.e. third document of type 12.

19.104-78. Basic inscriptions

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

As for the design of the LU, quite often at the enterprises a mixture is used - some of the inscriptions of the LU are drawn up according to ESPD, part - according to ESKD, and part - in their own way. Therefore, it is best to do the LU yourself, look for whether there is an enterprise standard (STO), or take an example from the local regulatory 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 next to the title page. But in the event that the LU is more than one (this happens if all the signatures did not fit on the sheet), then the LUs are numbered separately.

19.105-78. General requirements for program documents

A general structure of the document is introduced, independent of the method of its execution. Those. back in 1978 it was laid down in the standard that the document may not necessarily be paper. In particular, to introduce the concept of content for fully electronic documents. For paper design, common at that time, GOST 19.106-78 was adopted.
At present, this standard has to be addressed 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 ESPD, second only to the description of R-circuits. It is the main working standard for documentation. Introduces rules for the design of text, elements of the structure of the document, images, formulas, etc. However, unlike the corresponding 2.106 of ESKD, 19.106 is much less detailed, which leads to numerous uncertainties.
First, the standard does not actually define the line spacing and the amount of vertical space between headings. He introduces three rules for determining the interval: for typewritten text, machine and typographic.
The typewritten text is typewritten text. The displacement of the next line relative to the previous one was made automatically with the so-called “carriage transfer” - the transition to printing the next line, produced by moving a special lever. As a rule, the interval could be manually adjusted by turning the paper pulling shaft, and had a “setting” that allows you to set the interval size - 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 link to 13.1.002-2003, in which, unfortunately, the line spacing (and, by the way, the minimum font height) is set only for handwritten documents (section 4.2.5).
Typographical - text typed in the printing. Given the year of adoption of the standard, most likely we are talking about
[ Letterpress , where the line spacing is determined by the letters used. I am not an expert in typography, and there is very little information about typing methods.
Which interval to use as a result is often determined by local monitoring or SRT. Typical values ​​are one and a half spacing and 14 font size.
Often there are many questions about how to structure a document. 19.106 considers that the entire document is divided into sections, subsections, paragraphs and sub-paragraphs. All of them (except for the section and subsection) may have a title and not to have it. Wherein:
  • “The contents of the document include the number of sections, subsections, clauses and sub-clauses having a title” (paragraph 2.1.4). This is a direct indication that a sub-item may have a heading and be included in the table of contents;
  • “It is allowed to place text between the headings of a section and a subsection, between the headings of a subsection and a paragraph”. It is important to note that unnumbered text can only be between the headings, and only at the top 2 levels.

Unlike ESKD, in ESPD a strange way of drawing up pictures is adopted: first the name of the picture goes, then the picture itself, then the optional “caption text”, and then, on a new line, “Fig. N ”.
This standard has a number of “holes”, gaps. For example, it says: “illustrations, if they 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 the way they are numbered - within the entire document or within the page.
Tables The document itself provides a link to GOST 1.5.68. Judging by the first series, it is easy to conclude that this is a standard for developing standards. And here it is, is unclear. By meaning, it complies with the rules for the design of tables in the ESKD, with a few exceptions. This standard was canceled, instead of, after several iterations, 1.5-2012, in which the rules for the design of the table ... just disappeared. They were still in 1.5-2002, but disappeared already in 1.5-2004. In real life, we make out the table according to ESKD.
Applications. The standard does not indicate whether the figures, formulas and tables from the appendices fall into the general list. Similarly, it does not say whether the contents of the application should be disclosed in the table of contents if it contains its sections, clauses, etc. In our practice, we do not reveal the insides of applications.
Finally, it should be said about indents. A paragraph indent of 5 characters is common to:
  • red lines;
  • the indent of the structure of the document after the section (subsection, paragraph, subparagraph);
  • enum item.
    At the same time, 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 is one value, the point number is us by another interval, in the indented indents in the lists is so generally necessary.

    In the following parts I plan to get to the end of the list of ESPD standards.

Source: https://habr.com/ru/post/218735/

More articles:


All Articles