GOST 19.402-78
Group T55
INTERSTATE STANDARD
one system program documentation
PROGRAM DESCRIPTION
Unified system for program documentation. Program description.
MKS 35.080
Date of introduction 1980-01-01
By Decree of the USSR State Committee on Standards dated December 18, 1978 N 3350, the implementation date was set at 01/01/80
EDITION (January 2010) with Amendment No. 1, approved in September 1981 (IUS 11-81).
1. This standard establishes the composition and requirements for the content of the program document “Program Description”, defined by GOST 19.101-77.
The standard fully complies with ST SEV 2092-80*.
________________
* Access to international and foreign documents mentioned here can be obtained by following the link to the website http://shop.cntd.ru. - Database manufacturer's note.
(Changed edition, Amendment No. 1).
2. The structure and design of the document is established in accordance with GOST 19.105-78.
Drawing up the information part (annotations and contents) is mandatory.
3. The description of the program must contain the following sections:
general information;
functional purpose;
description of the logical structure;
used technical means;
input data;
output.
Depending on the features of the program, it is possible to introduce additional sections or combine individual sections.
4. In the section " General information" must be indicated:
designation and name of the program;
software necessary for the operation of the program;
programming languages in which the program is written.
5. The “Functional Purpose” section must indicate the classes of problems being solved and (or) the purpose of the program and information about functional restrictions on application.
6. In the section "Description of the logical structure" the following should be indicated:
program algorithm;
methods used;
program structure with description of functions components and connections between them;
connection of the program with other programs.
The description of the logical structure of the program is carried out taking into account the text of the program in the source language.
3-6. (Changed edition, Amendment No. 1).
7. The section “Technical means used” must indicate the types of electronic computers and devices that are used when running the program.
method of calling the program from the corresponding storage medium;
entry points into the program.
It is allowed to indicate download addresses, usage information random access memory, program volume.
9. In the "Input data" section the following must be indicated:
character, organization and preliminary preparation input data;
format, description and method of encoding input data.
10. In the “Output data” section the following must be indicated:
nature and organization of output data;
format, description and method of encoding the output data.
11. It is allowed to illustrate the contents of sections with explanatory examples, tables, diagrams, graphs.
12. The appendix to the program description may include various materials that are inappropriate to include in sections of the description.
7-12. (Introduced additionally, Amendment No. 1).
Electronic document text
prepared by Kodeks JSC and verified against:
official publication
Unified system of program documentation:
Collection national standards. -
M.: Standartinform, 2010
V.E. Karpov
This document contains short description 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 jargon-like 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 hard disk drive, flat disk drive, hand-held manipulator such as “mouse” (or “bun”, 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.
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. Leisurely. 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 executing development documentation, rules for executing manufacturing documentation, rules for executing maintenance documentation, rules for executing operational documentation, rules for handling 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 task. 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. Program description.
- 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. Guide maintenance. 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 tendencies design of programs and program documentation; 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 program documents provided for by the ESPD standards is not at all as “rigid” as it might seem: the standards allow you to include in the set of documentation on software system(PS) additional types, and, secondly, based on the customer’s requirements, some changes in both the structure and content of the established types of PD are permissible. Moreover, it can be noted that the ESPD standards (and this applies to all other standards in the field of PS - GOST 34, International standard ISO/IEC, 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 speeches of various figures are usually inserted here (this is 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 radical socio-economic transformations...etc." In general, the main thing Don't overdo it here.
And further. When describing his product, the developer often confuses the concepts of component and complex. This - different types programs. A component is defined as “a program considered as a single whole, performing a complete function and 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 the addition to technical specifications carried out in the same order 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 characteristics of the program or software product, it is possible to clarify the content of sections, introduce new sections, or combine individual ones.
In chapter Name and scope indicate the name, brief description the scope of application of the program or software product and the object in which the program or software product is used.
In chapter 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 development topics.
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 ___. , and so on.
In chapter 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 ...
Initial data: text file with a 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. The 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 compatible PCs,” “The program should be designed for a non-professional user.” and so on.
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 - a compatible PC with graphics adapter EGA (VGA). Necessary disk space- at least 600 KB, the amount of free RAM - 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 should be specified, source codes, programming languages. 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 case here indicate the requirements for labeling the software product, packaging options and methods. 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.
- Preliminary design. At this stage, the structures of input and output data are developed in detail, and the form of their presentation is determined. Under development general description algorithm, the algorithm itself, program structure. 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 equipment 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 guide.
These are standard requirements. If the Customer agrees that not all of this list can be presented, then this means that his intentions towards 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 chapter Control and acceptance procedure the types of tests must be specified and General requirements for acceptance of work. 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:
|
Development stages |
Stages of work |
|
|
Technical task |
Justification for the need to develop the program |
Formulation of the problem. |
|
Research work |
Determining the structure of input and output data. |
|
|
Development and approval of technical specifications |
Determining program requirements. |
|
|
Preliminary design |
Development of a preliminary design |
Preliminary development of the structure of input and output data. |
|
Approval of the preliminary design |
|
|
|
Technical project |
Technical project development |
Clarification of the structure of input and output data. |
|
Approval of technical design |
Development of an action plan for the development and implementation of programs. |
|
|
Working draft |
Program development |
Programming and debugging |
|
Development of software documentation |
Development of program documents in accordance with the requirements of GOST 19.101-77. |
|
|
Program testing |
Development, coordination and approval of the test program and methodology. |
|
|
Implementation |
Preparation and transmission of the program |
Preparation and transfer of programs and software documentation for maintenance and (or) production. |
Notes:
- 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.
- 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: Program "Automated workplace ACS developer" is intended for... implemented on.... The program supports...
In chapter 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 chapter " 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 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 the program diagrams should be written).
When describing the program logic, a link to the program text is necessary.
In chapter Composition and functions indicate a description of the composition and function of programs and the methods used to solve problems.
In chapter 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 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 personal computer(PC) type IBM PC/AT. 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.
Everyone's text program file begins with a “header” that states:
- 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(); hang_system(); ) write_something(anything); display_copyright_message(); do_nothing_loop(); do_some_stuff(); if(still_not_crashed) ( display_copyright_message(); do_nothing_loop(); basically_run_windows_3.1(); do_nothing_loop (); 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"); */ printf("Welcome to Windows 98"); if(system_ok()) crash(to_dos_prompt ) 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 effort and time.
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 the MS DOS operating system (version no lower than 3.0) on a PC such as IBM PC/AT, as well as on compatible ones. An EGA (VGA) adapter is also required for operation.
Test procedure:
- The program is launched….
- Selected...
- Pressed...
- 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 last one 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 abstract is posted on 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 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 with right side pages, 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 annex).
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 designed as a continuation of this document on subsequent pages or issued as a separate document.
Every application must start with new page with indication on the right top corner the words "Application" and have a thematic title. 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 releasing the application as a separate document, on title page The word “Appendix” should be indicated under the name of the document, and if there are several attachments, its serial number should also be indicated.
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
|
Unified system of program documentation |
GOST 19.402-78*(ST SEV 2092-80) |
PROGRAM DESCRIPTION |
|
|
United system for program documentation. Program description |
By Decree of the USSR State Committee on Standards dated December 18, 1978 No. 3350, the introduction date was established
from 01.01. 1980
1. This standard establishes the composition and requirements for the content of the program document “Program Description”, defined by GOST 19.101-77.
The standard fully complies with ST SEV 2092-80.
2. The structure and format of the document are established in accordance with GOST 19.105-78.
Drawing up the information part (annotations and contents) is mandatory.
3. The description of the program must contain the following sections:
general information;
functional purpose;
description of the logical structure;
technical means used;
input data;
output.
Depending on the features of the program, it is possible to introduce additional sections or combine individual sections.
4. In the “General Information” section the following must be indicated:
designation and name of the program;
software necessary for the operation of the program;
programming languages in which the program is written.
5. The “Functional Purpose” section must indicate the classes of problems being solved and (or) the purpose of the program and information about functional restrictions on use.
6. In the section “Description of the logical structure” the following should be indicated:
program algorithm;
methods used;
program structure with a description of the functions of its components and the connections between them;
connection of the program with other programs.
The description of the logical structure of the program is carried out taking into account the text of the program in the source language.
3-6.(Changed edition, Amendment No. 1).
7. The section “Technical tools used” must indicate the types of electronic computers and devices that are used when running the program.
method of calling the program from the corresponding storage medium;
entry points into the program.
You can specify download addresses, information about RAM usage, and program size.
9. In the “Input data” section the following must be indicated:
nature, organization and preliminary preparation of input data;
format, description and method of encoding input data.
10. In the “Output data” section the following must be indicated:
nature and organization of output data;
format, description and method of encoding the output data.
11. It is allowed to illustrate the contents of sections with explanatory examples, tables, diagrams, graphs.
12. The appendix to the program description may include various materials that are inappropriate to include in sections of the description.
7-12.(Introduced additionally, Amendment No. 1).
* Reissue (November 1987) with Change No. 1, approved in September 1981 (IUS 11-81)
INTERSTATE STANDARD
The standard fully complies with ST SEV 2092-80.
2. The structure and format of the document are established in accordance with GOST 19.105-78.
Drawing up the information part (annotations and contents) is mandatory.
3. The description of the program must contain the following sections:
input data;
output.
Depending on the features of the program, it is possible to introduce additional sections or combine individual sections.
4. In the “General Information” section the following must be indicated:
designation and name of the program;
methods used;
program structure with a description of the functions of its components and the connections between them;
connection of the program with other programs.
The description of the logical structure of the program is carried out taking into account the text of the program in the source language.
3-6.(Changed edition, Amendment No. 1).
7. The section “Technical means used” must indicate the types of electronic computers and devices that are used when running the program.
nature, organization and preliminary preparation of input data;
format, description and method of encoding input data.
10. In the “Output data” section the following must be indicated:
nature and organization of output data;
format, description and method of encoding the output data.
11. It is allowed to illustrate the contents of sections with explanatory examples, tables, diagrams, graphs.
12. The appendix to the program description may include various materials that are inappropriate to include in sections of the description.
7-12.(Introduced additionally, Amendment No. 1).
By Decree of the USSR State Committee on Standards dated December 18, 1978 No. 3350, the introduction date was established
from 01.01. 1980
1. This standard establishes the composition and requirements for the content of the program document “Program Description”, defined by GOST 19.101-77.
The standard fully complies with ST SEV 2092-80.
2. The structure and design of the document is established in accordance with GOST 19.105-78.
Drawing up the information part (annotations and contents) is mandatory.
3. The description of the program must contain the following sections:
- general information;
- functional purpose;
- description of the logical structure;
- technical means used;
- input data;
- output.
Depending on the features of the program, it is possible to introduce additional sections or combine individual sections.
4. In the “General Information” section the following must be indicated:
- designation and name of the program;
- software necessary for the operation of the program;
- programming languages in which the program is written.
5. The “Functional Purpose” section must indicate the classes of problems being solved and (or) the purpose of the program and information about functional restrictions on use.
6. In the section “Description of the logical structure” the following should be indicated:
- program algorithm;
- methods used;
- program structure with a description of the functions of its components and the connections between them;
- connection of the program with other programs.
The description of the logical structure of the program is carried out taking into account the text of the program in the source language.
3-6.(Changed edition, Amendment No. 1).
7. The section “Technical tools used” must indicate the types of electronic computers and devices that are used when running the program.
- method of calling the program from the corresponding storage medium;
- entry points into the program.
You can specify download addresses, information about RAM usage, and program size.
9. In the “Input data” section the following must be indicated:
- nature, organization and preliminary preparation of input data;
- format, description and method of encoding input data.
10. In the “Output data” section the following must be indicated:
- nature and organization of output data;
- format, description and method of encoding the output data.
11. It is allowed to illustrate the contents of sections with explanatory examples, tables, diagrams, graphs.
12. The appendix to the program description may include various materials that are inappropriate to include in sections of the description.
7-12.(Introduced additionally, Amendment No. 1).
* Reissue (November 1987) with Change No. 1, approved in September 1981 (IUS 11-81)