To describe program, start with a general introduction. Describe the main problem the user is facing. Naturally, this should be the very problem that the described program solves. By the way, this is a good way to immediately outline the target audience of users. Those who find it useful and necessary will download or buy it. Other users will save time and not read further. Also in the introduction, briefly describe the main features of the program. 1-2 sentences are enough for this.
Specify system requirements for computer hardware. To best describe program, make a gradation. List the minimum requirements and requirements for comfortable work.
Describe the interface and workspace. To describe program more clearly, use screenshots of its different working windows and states. Describe the main toolbars, menu item layout, status bars, etc.
Impossible to describe program, without going into detail about its main functions. This can be done in the form of a list or list. However, it is important to be specific at this point. For example, the phrase “effective work with projects” does not carry any semantic meaning. More precisely, there is, of course, a semantic load, but it is relative and does not tell the reader any facts.
Having indicated the main functions of the program, describe its additional functions that may be especially convenient and useful to the user. For example, these could be the ability to quickly integrate with other software, improvements in speed, user-friendly design elements, etc.
To describe program new version, tell us about the changes that it has undergone since its previous update. Describe what functionality was removed, what problems were solved, what was new, what was changed, finalized and improved. Differences from previous versions can also be presented as a list.
Make a conclusion in which you once again emphasize the target audience and the main purpose of the program, mentioning its winning aspects.
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 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 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 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. 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 program documents provided for by the ESPD standards is not at all as “rigid” as it might seem: the standards allow additional types to be added to 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 further. 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, 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 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 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, 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 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 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 ___. , 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 ...
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. 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 - 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, this indicates the requirements for labeling a 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. 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 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 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 chapter 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:
|
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: The program "Automated workstation for self-propelled guns 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 the graphic formats - copies of the image of the constructed characteristics (frequency response, phase response, 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 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) yte_swapfile (); do_nothing_loop (); totilla_screw_up_hpfs_file_system (); search_and_destroy_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 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 abstract 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 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. Appendices are drawn up as a continuation of this document on subsequent pages or issued as a separate document.
Each application must start 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.
Program text
Example.
Program specification
The specification section provides the exact name of the program and its composition. The specification form is given in Appendix 2. The specification columns are filled out as follows:
1.
in the "Designation" column indicate the designation of the main software
components;
2. in the “Name” column indicate the full name of the corresponding component;
3. in the "Note" column - additional information related To programs written in the specification.
The executable file of the "Game "Labyrinth"" program is named Labirint.exe and is located on drive F in the Student\Kursov\Labirint directory. Project composition:
| Name | Designation | Note |
| Acl | Floor plan file | Created in the application |
| Helpi | Help file | Created in the application |
| Labirint.Dof | Project Settings File | Contains current project settings: compiler and linker settings, service directory names, conditional directives |
| Labirint.Dpr | Project file | Links all the files that make up the application |
| Labirint.Dsk | File containing Desktop project settings | Contains information about which windows are open and in what positions they are located |
| Labirint.Res | Resource File | Contains pictograms, graphic images |
| Unit 1.Pas | Software module file for form No. 1 | Defines the functionality of form No. 1. |
| Unit2.Pas | Software module file for form No. 2 | Defines the functionality of form No. 2. |
| U»it3.Pas | Software module file for form No. 3 | Defines the functionality of form No. 3. |
| Unitl.Dfm | Form file #1 | Contains a list of properties of all components included in form No. 1. |
| Unit2.Dfm | Form file #2 | Contains a list of properties of all components included in form No. 2. |
| Unit3.Dfm | Shape file #3 | Contains a list of properties of all components included in form No. 3. |
| Uuitl.Dcu | Object file for Unit1. Pas | Compiled version of Unit1.Pas. |
| Uuit2.Dcu | Object file for Unit2.Pas | Compiled version of Unit2.Pas. |
| Unit3.Dcu | Object file for Unit3.Pas | Compiled version of UnM.Pas. |
A complete listing of the program is provided. Listings of all modules with comments are provided.
The “Program Description” section according to GOST 19.402-78 should contain the following subsections:
· general information;
· functional purpose;
· description of the logical structure;
· technical means used;
· input data;
· output.
Individual sections can be combined. Some points in this section repeat sections of the technical project. Such repetitions are provided for by GOST, since at the stage of the detailed design some additions or changes arise in the composition of the technical means or program. More specific and accurate data is provided here.
The “General Information” subsection should indicate: designation and name of the program; software necessary for the operation of the program; programming languages in which the program is written.
The subsection "Functional purpose" must indicate the classes of problems being solved and (or) the purpose of the program and information about functional restrictions on use.
The subsection "Description of the logical structure" should indicate the 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.
The subsection “Technical means used” must indicate the types of computers and devices that are used when running the program.
The “Call and Load” subsection must indicate the method for calling the program from the appropriate storage medium and the entry points into the program.
The subsection "Input data" must indicate: the nature, organization and preliminary preparation of input data, format, description and method of encoding input data.
The subsection "Output data" must indicate: the nature, organization and preliminary preparation of the output data, format, description and method of encoding the output data.
Why do you need an application description?
To quote Captain Obvious, it's important to let your customers know what your app is about. What is it for? From a developer’s point of view, the description is an opportunity to “hook” the buyer. You need to sell the idea. You need to tell them why they should download your app and not any other.
Anyone reading your description has already found your app in search. The title and screenshots already seemed attractive enough for him to click the “more” button. Figuratively speaking, he has already taken out his wallet; all that remains is to force him to pay for the purchase.
Introduction
You have a limited number of words at your disposal. Take a look at the description of the applications - there are only a couple of lines under the icon in the App Store.
The most severe restrictions are imposed by the iPhone screen - you only have 225 characters. This is the most important part of your description. The entire description is limited to four thousand characters, but it is the first two hundred that determine whether buyers want to read the rest.
You need to express yourself clearly and clearly. The name of the application - and screenshots - should already tell the buyer in general what it is. Now we need to strengthen this impression.
The introduction to the description should be a call to action. Try to put yourself in your customer's shoes. What does he need?
There are a few simple rules here.
- Capture your buyer's attention. Place nouns and verbs at the beginning of the sentence to make the phrase dynamic and as clear as possible.
- Don't use jargon, it can be off-putting. Cut off everything unnecessary: introductory words, adverbial phrases, overly flowery expressions.
- What is the value of your application? What will the buyer get, learn or experience when they download it?
- To see what your app description will look like on the iPhone or iPad screen, use the free preview.
- Now that the bait is on the hook, it’s time to cast the line. In other words, we’re done with the introduction, let’s continue with the description.
Details
Explain what exactly the user will get from your application. After a couple of introductory phrases—an emotional call to action—offer them the details.
How you distribute the information depends on the specific application you have. But in summarizing, you should adhere to the same principles as journalists writing news stories - the most important information comes first, the less important information comes last.
Don't neglect paragraphs. People get scared when they see a text “canvas”. Vary the length of the sentence - this makes the text more expressive. Use subheadings and line breaks. Lists are also a good way to break up text and make it more attractive.
Lists
While we're on the topic of lists, they are the easiest and most popular way to communicate the features of your app. Here are some tips on how to use them correctly:
- don't make them too long;
- Place the two most important points at the top of the list, the rest at the bottom;
- You probably didn’t read this paragraph;
- You definitely won't read this one.
It is tempting to write down all the features of an application in a list. You can try, but keep in mind that people usually read the first two paragraphs and the last one. They skip the middle, just like sentences that begin with the same words.
So it would be better to break a long list into several small ones, united by one topic.
Search
People who search for an app in iTunes don't look at the description; they tend to pay more attention to the title, keywords, and other factors. However, keywords in the description are indexed by search engines. Thus, a proper description is the key to high search rankings.
Your description must contain keywords. It's important not to overdo it. They must be appropriate. Don’t try to write overtly “selling” text - it will inevitably alienate the potential user. If you need help and the prospect of paying for it doesn’t put you off, you can contact Appnique or Sensor Tower (for English-language texts, editor’s note).
Localization
Localizing your app is a relatively inexpensive and easy way to increase downloads. It has virtually no flaws. A study conducted by Common Sense Advisory of 3,000 consumers from 10 non-English speaking countries shows that more than 75% of respondents want an app in their native language.
The report, entitled “If I Don’t Read, I Don’t Buy,” also states that 55% of users only make purchases on sites that provide information in their native language. Interestingly, 50% of respondents noted that they would be satisfied even with navigation and some of the content in their native language. That is, even a partial translation will give better results than its complete absence.
Considering this fact, translate at least the description, if not the entire application.
Provides a list of localized applications with the ability to sort by genre - thus, it is possible to analyze where it is better to concentrate your efforts. You can also see a list of the most used words in the app description in different languages.
Make sure that the translation company has the appropriate skills. Google Translate is unlikely to be able to convey the shades of meaning that you put into the text.
If a popular website or celebrity wrote a review of your app, then it’s worth quoting them. If you've won an award, that should be mentioned too. If your app is very popular among your family... It's probably better to remain silent (unless, of course, your last name is Kardashian).
Apple's rules stipulate that you can "only place user reviews, praise, or recommendations at the end of the description if you deem it necessary."
Updates
Don't think that the app's description is akin to the Ten Commandments and is set in stone. You, obviously, will have to report what's new in the application after the update. Plus, if you suddenly come up with a brilliant phrase, or users share a remark that inspired you, or the best website on the entire Internet left a cool review of your app, don’t hesitate to improve your description. If there were errors in the application that affected the work, do not forget to inform them after they have been fixed that they have been fixed.
The description is not only a window into your application, but also an opportunity to get a high search ranking.
There are four things to consider to benefit from referencing/citations. Firstly, you always need to have a website for your application - with screenshots, texts and links where you can buy it. Secondly, you need a link to the support team - an email or forum address where you can write if you have any questions or problems. Third, links to your project page on social networks. And lastly, you need links to your other applications.
Make sure your support team responds to queries immediately. If people have a hard time connecting with you, they will leave you low ratings and maybe even write a nasty review.
If users keep asking the same questions, consider creating an FAQ section on the app's website.
If you already have a successful project, don't forget to mention it. Or you can leave a “if you liked this, you might like this” description at the end of your other app.
Common mistakes and how to avoid them
Typos and punctuation/grammatical errors. Invite a specially trained copywriter or, as a last resort, turn on spell check in your text editor.
Confused and tongue-tied description. If the user does not understand you, then he will not download the application.
Abuse of hyperbole and clichés. Is your app really revolutionary? Is the company really young and dynamically developing? Find less cliché ways to communicate this.
Everything secret becomes clear. The truth about your app will be revealed within seconds of downloading - and then stored in Google's cache forever. So don't lie.
Too many keywords. I already mentioned that clumsy attempts to cram as many keywords into the text as possible will only turn off the buyer.
The description does not take into account the interests of the target audience. Write not for yourself and not for competitors - write for the buyer.
Important details are missing. How much does the application weigh? How much does a subscription cost? This is not information that should be ignored.
So let's get started
To summarize briefly: you need to prepare, write, polish, translate and then update as necessary.
Do your research and preparation before you start writing your description. Find the right keywords and phrases. Write down the features of your application in a list and rank them from most important to least important.
Write a draft description or hire a talented copywriter for this purpose.
Edit, adjust and rewrite for maximum effect. Check how the description will look on the iPhone or iPad screen. Work until it is smooth, polished and attractive.
Translate it into additional languages, starting with those that are especially important in terms of downloads.
Make sure the description reflects any changes that have happened to your app, highlight major improvements in the descriptions, and highlight positive reviews or awards.
A good app description will help sell it and encourage downloads.
3. DESCRIPTION OF THE PROGRAM STRUCTURE
Description of Variables
The variable descriptions section describes variables whose purpose is given in Table 3.1.
Table 3.1 – Description of program variables
| Name | Type | Purpose |
| FO,FS | TextFile | Source and result text file variable |
| tmpstr,str,strslovo | String | String variables for reading from a file |
| i,j | integer | Variable counters for loops |
| count | integer | The variable stores the number of corrected characters |
| answ | Word | Used to determine the user's answer to a question about correcting a character |
| UpCh | set of char | Lots of capital characters |
| ZnCh | set of char | Multiple word separator characters |
| OFName | String | A string containing the path to the source file |
| SFName | String | A string containing the path to the resulting file |
The program contains a description of one auxiliary procedure.
The FormCreate procedure outputs initial values to form components for correct display of the form at the beginning of the program.
The Button1Click procedure for opening the source file and saving the path to it.
The Button2Click procedure for opening the resulting file and saving the path to it.
Main program algorithm
The algorithm for executing the main body of the program is shown in Figure A.1 in Appendix A. So in the procedure, first of all, the file is bound to a file variable and the text file is opened to read text information.
Then the information is read from the file line by line.
Then the words on each line are highlighted.
Then the selected words are searched for capital characters.
Then the changes are written to the resulting text file.
During the work, the following operations with text files were used:
AssignFile(<Имя файловой переменной>,<Имя файла>);
The file name is specified either as a string constant or through a variable of type Sting. The file name must match the rules of the currently running operating system. If the name string is empty, then the file variable is associated with a standard I/O device.
Reset (<Имя файловой переменной>);
A file is opened to read information from it, and it is assigned the name specified by the Assign procedure.
After working with a file, it should usually be closed using the CloseFile procedure (<Имя файловой переменной>). Information is output by the WRITELN(f: TextFile;S: String) operator. After its execution, the string S is added to the end of the file associated with the variable f.
4. DESCRIPTION OF INPUT DATA
The input data for execution is a file that contains uppercase characters.
5. DESCRIPTION OF OUTPUT DATA
The output is:
A message about the completion of checking the file for the presence of capital characters;
Message about the number of corrected characters;
The completed resulting text file.
6. OPERATOR INSTRUCTIONS
The developed program is an executable file Luchshev.exe with a size of 405 KB. The program implements an algorithm for checking a text file for the presence of capital characters.
After starting the program, the window shown in Figure 4.1 appears.
Figure 4.1 – Main window of the program
After this, the user must specify the path to the file. Figure 4.2 shows an example of a dialog box for opening a file.
Figure 4.2 – Example of opening a source file
An example of a message about finding a capital character is shown in Figure 4.3.
Figure 4.3 – Message about finding a capital character
An example of a window with the result of checking a text file is shown in Figure 4.4.
Figure 4.4 - Resulting window.
The result of the check is written to the selected result file located in the selected directory.
The functioning of the program fully corresponds to the task.
This course work was completed in full accordance with the assigned task and debugged in the Delphi 7.0 environment. During the course work, a program was developed to check a text file.
During the course project, an analysis of the technical specifications and formulation of the design problem were carried out.
The functions that the developed program should have were highlighted.
A program algorithm was developed to perform the generated functions.
According to the developed algorithm, a program was compiled and debugged in the Delphi algorithmic programming language. During the development of the program, it was tested and debugged on test sets. An operator instruction has been developed for the written program indicating the order of actions to be performed.
The results of the work are presented in the form of an explanatory note.
During the development of the program, the following work skills were consolidated:
I/O commands both to the screen and to text files,
Using procedures
Array processing commands
Commands for implementing cycles with a given number of repetitions;
Commands for checking conditions and implementing branches.
As a result of completing this course work, we were convinced of the wide capabilities of the Delphi programming language and consolidated practical programming skills in the Delphi environment.
List of links
1. Zuev E.A. Programming in Delphi 6.0,7.0. – M.: Radio and communications, Vesta, 1993.
2. Faronov V.V. Delphi 7.0. Beginner course. - M.: Knowledge, 2000.
| |
Program algorithm
Figure A.1 – Program algorithm
Figure A.2 – Algorithm of the main program procedure
APPENDIX B
Program listing
4. Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
5. Dialogs, StdCtrls;
7. TForm1 = class(TForm)
8. Button1: TButton;
9. Button2: TButton;
10. OpenDialog1: TOpenDialog;
11. SaveDialog1: TSaveDialog;
12. Button3: TButton;
13. Label1: TLabel;
14. Label2: TLabel;
15. Label3: TLabel;
16. Label4: TLabel;
17. Button4: TButton;
18. procedure Button1Click(Sender: TObject);
19. procedure Button2Click(Sender: TObject);
20. procedure FormCreate(Sender: TObject);
21. procedure Button3Click(Sender: TObject);
22. procedure Button4Click(Sender: TObject);
24. (Private declarations)
26. (Public declarations)
29. Form1: TForm1;
30. OFName,SFName:String;
31.implementation
33. procedure TForm1.Button1Click(Sender: TObject);
35. if OpenDialog1.Execute then
36. OFName:=OpenDialog1.FileName;
37. if OFName<>"" then begin
38. Button1.Enabled:=False;
39. Button2.Visible:=True;
40. Label1.Caption:="Path to the file to check: "+OFName;
41. Label2.Visible:=True;
45. procedure TForm1.Button2Click(Sender: TObject);
50. if SaveDialog1.Execute then
51. SFName:=SaveDialog1.FileName;
52. if Pos(".txt",SFName)=0 then SFName:=SFName+".txt";
53. if SFName=OFName then
54. ShowMessage("Select another file to save the result")
57. if (SFName<>"") and (b) then begin
58. Button2.Enabled:=False;
59. Label2.Caption:="Path to the resulting file: "+SFName;
60. Button3.Visible:=True;
61. Label3.Visible:=True;
62. Label3.Caption:="To start checking, click on the "Check" button";
65. procedure TForm1.FormCreate(Sender: TObject);
67. Button2.Visible:=False;
68. Label2.Visible:=False;
69. Button3.Visible:=False;
70. Label3.Visible:=False;
71. Button4.Visible:=False;
72. Label4.Visible:=False;
73. Label1.Caption:="Click on the "Open" button and select the file to check";
75. procedure TForm1.Button3Click(Sender: TObject);
77.FO,FS:TextFile;
78. i,j,count:integer;
79. str,strslovo,tmpstr:String;
80. ZnCh,UpCh:set of Char;
84. ZnCh:=[".",",",","!","?"];
85. UpCh:=["A".."Z","A".."Z"];
86. AssignFile(FO,OFName);
87. AssignFile(FS,SFName);
91. if IOResult<>0 then begin
92. ShowMessage("There were problems opening the file. The program will be terminated");
96.Rewrite(FS);
97. while not Eof(FO) do begin
98. Readln(FO,str);
99. strslovo:="";
100. for i:=1 to Length(str) do begin
101. if (str[i] in ZnCh) or (str[i]=" ") then begin
102. for j:=1 to Length(strslovo) do begin
a. if strslovo[j] in UpCh then begin
b. answ:=MessageDlg("A capital letter ""+strslovo[j]+" was found in the word ""+strslovo+"". Replace it with a small one?",mtInformation,,0);
c. if answ=mrYes then begin
i. tmpstr:=strslovo[j];
ii. tmpstr:=AnsiLowerCase(tmpstr);
iii. Delete(strslovo,j,1);
iv. Insert(tmpstr,strslovo,j);
104. Write(FS,strslovo+str[i]);
105. strslovo:="";
108. strslovo:=strslovo+str[i];
110. Writeln(FS,"");
112. CloseFile(FO);
113. CloseFile(FS);
114. Label3.Caption:="File verification completed. Corrected "+IntToStr(count)+" capital letters.";
115. Button3.Enabled:=False;
116. Button4.Visible:=True;
117. Label4.Visible:=True;
120. procedure TForm1.Button4Click(Sender: TObject);
122. OFName:="";
123. SFName:="";
124. Button1.Enabled:=True;
125. Button2.Visible:=False;
126. Button2.Enabled:=True;
127. Button3.Visible:=False;
128. Button3.Enabled:=True;
129. Button4.Visible:=False;
130. Label2.Visible:=False;
131. Label3.Visible:=False;
132. Label4.Visible:=False;
133. Label1.Caption:="Click on the "Open" button and select the file to check";
| |
Program solution results
