Today we will talk about domestic standards for project documentation. How these standards work in practice, why they are bad and why they are good. When developing documentation for public and serious private customers, we usually have no choice - compliance with standards is included in the requirements for documenting technical specifications. In practice, I had to deal with various examples of misunderstanding of the structure of standards, what should be in the documents and why these documents are needed. As a result, sometimes such gems come out from the pen of technical writers, analysts and specialists that it is not clear in what state of consciousness they were written. But in fact, everything is quite simple. A search on Habr did not return links to more or less complete material on this topic, so I propose to fill in this annoying gap.
What are Documentation Standards?
In the 34 series in question, there are only 3 main documentation standards:The most beloved and popular standard for the development of technical specifications. The only thing you should not forget is that it is tightly connected with other standards of the series, and if you have received a technical specification made according to this standard, it is highly desirable to adhere to other standards, even if there are no direct requirements for this. At least in terms of common ideology(about which below)
This is the core document that complete list documentation GOST 34, recommendations for coding documents, which stages of the project the documents belong to (the stages are described in GOST 34.601-90), and also how they can be combined with each other.
In fact, this standard is a large table with comments. It can be driven into Excel for ease of use.
A voluminous standard describing the content of project documents with varying degrees of detail. The above-mentioned GOST 34.201-89 is used as an index.
There are many questions and interpretations of its provisions to the RD 50-34.698-90 standard, which, due to their vagueness, are often understood differently by the customer and the contractor or even members of the project team. But, unfortunately, we don't have anything more specific.
Consider now the pros and cons of standards, traditionally starting with the cons.
Cons of standards
The main disadvantage is obvious to everyone - the standards are old. They contain an outdated idea of the architecture of an automated system. For instance:- two-tier applications, consisting of a client program and a DBMS server (no three- or more "tier" applications, no Weblogic or JBoss)
- the structure of the database tables, being described, will give an idea of the logical data model (the fact that there could be some kind of Hibernate between the application and the database seemed like a bad overkill then)
- the user interface is single-window (is there any other? And what is a “browser”?)
- There are few reports in the system, they are all paper and printed on a dot matrix printer
- The developed program is focused on solving the "information processing problem", which has a clear input and output and is highly specialized. At the heart of information processing is an "algorithm". Sometimes there are several "algorithms". (Object-oriented programming then took only its first steps and was not seriously considered).
- the database administrator understands what information is in the tables and actively participates in editing system directories (is there really one DBMS server for 50 different applications?)
5.8. Document shape drawing (video frame)
The document must contain an image of the form of the document or video frame in accordance with the requirements state standards unified documentation system R 50-77 and necessary explanations.
The meaning of the document is that the so-called "Printing Areas" were used at Soviet enterprises, where high-speed dot matrix printers were located, the drivers for which were often written by the engineers themselves. Therefore, they had to maintain a register of all documents that needed to be printed to ensure that when printed, the documents would look the way they should.
A "video frame" is also a document that was displayed on a text display. The displays did not always support the required characters and the required number of horizontal characters and vertical lines (and did not support graphics at all). Therefore, here, too, it was necessary to additionally coordinate the forms of all screen documents.
Now the words “mashinogram”, “video frame”, “ATsPU” do not tell us anything. I also did not find them in use, although I graduated from a specialized institute in the 90s. It was the time when Windows 3.1 appeared, VGA displays, three-inch floppy disks and the first domestic Internet sites. But these words are in the standard, and the customer sometimes capriciously demands to provide him with a complete set of documentation in accordance with GOST 34.201-89. Moreover, such wording in the TOR wanders from one ministry to another and has already become a kind of unspoken template into which the content is hammered.
So a document with a stupid name "Drawing of the form of a document (video frame)" in the project must be and must not be empty.
What is good in the standard
Any standard is good already because it allows the customer and the contractor to speak the same language and guarantees that, at least, the customer will not have any claims “in form” to the transmitted results.
And GOST 34 standards are also good because they were drawn up smart people, have been run in for years and they have a clear goal - to describe as fully as possible on paper the complex abstract entity that any automated control system represents.
When you need to competently set a task for Western contractors who have never heard of our GOSTs, you can also rely on these standards, or rather on their content, the semantic component. Because, I repeat, the guarantee of completeness of information is worth a lot. No matter how we amuse ourselves with the high level of our professionalism, we can forget to include elementary things in our requirements, while the same GOST 34.602-89 “remembers” everything. If you do not understand what the result of the work of Western contractors should look like, look at the requirements for documentation, for the recommended sections. I assure you, it's better not to think! Most likely, there are Western analogues of our standards, in which everything can be fuller, more modern and better. Unfortunately, I am not familiar with them, since there has not yet been a single case where our GOSTs were not enough.
You can laugh that the standards creators didn't know anything about java or .NET, about HD monitors and the Internet, but I wouldn't advise underestimating the scope of their work and its value to our professional community.
How to read and understand GOST Series 34 Documentation Standards
The standard divides all documents along two axes - time and subject area. If you look at table 2 in GOST 34.201-89, then this division is clearly visible (columns "Creation stage" and "Part of the project"
Stages of creating an automated control system
The stages of creation are defined in GOST 34.601-90. Three of them are relevant for documentation:- Draft design (EP)
- Technical design (TP)
- Development of working documentation (RD)
Technical project describes the future system from all angles. Documents of the TP stage, after reading, should leave behind complete clarity in the proposed approaches, methods, architectural and technical solutions. In the next phase, it will be too late to describe approaches and justify technical solutions, so the phase P is the key to successful delivery works, since the whole variety of requirements of the TOR should be reflected in the documents of the P phase. At the P stage, the system may not exist at all.
Working documentation is designed for the successful deployment, commissioning and further operation of the new system. These are documents containing very specific information that describe physically existing entities, in contrast to the P phase, which describes future splendor.
Parts (sections) of project documentation for the creation of automated control systems
The subject area is divided into "Provisions". At first it seems that such a division is redundant and unnecessary. But when you start working with this toolkit in practice, the ideology invested in it gradually comes to light.The automated system in the view of the compilers of GOST is a combination of hardware, software and communication channels that processes information coming from different sources in accordance with certain algorithms and produces processing results in the form of documents, data structures or control actions. Primitive model of the simplest automaton.
In order to fully describe this "automaton", the following cuts are made (as in drawing):
Mathematical software (MO), answering the questions: what logic is wired inside the "black box"? Why are these particular algorithms, exactly these formulas and precisely these coefficients chosen?
The software knows nothing about processors or databases. This is a separate abstract area, the abode of "spherical horses in a vacuum." But software can be very closely related to the subject area, aka Real life. For example, control algorithms for control systems road traffic it is required to coordinate with the traffic police before they are coordinated by the customer. And then you understand why they are singled out in a separate book. Because no one in the traffic police is interested in what OS the application server will run on, but what sign and speed limit will pop up on the scoreboard in rain or snow is very interesting. They are responsible for their part, and they are not going to sign anything else. On the other hand, when they signed, there will be no questions to the technical side of the issue - why they chose those and not other scoreboards or traffic lights. The wisdom of the "ancestors" is manifested in such practical cases.
Information support (IS). Another slice of the system. This time the black box of our system becomes transparent and we look at the information circulating in it. Imagine a model of the human circulatory system when all other organs are invisible. Here is something similar and there is information support. It describes the composition and routes of information flow inside and outside, the logical organization of information in the system, the description of directories and coding systems (whoever made programs for production knows how important they are). The main descriptive part falls on the TP stage, but some “rudiments” flow into the RD stage, like the “Database Catalog” document. It is clear that earlier it contained exactly what is written in the title. But today try to create such a document for a complex complex system, when purchased subsystems with their mysterious information repositories are very often used as part of the system. I'm not talking about the fact that this document is not particularly needed now.
Or here is the "Statement of machine storage media." It is clear that earlier there were numbers of magnetic drums or film reels in it. Now what should be included?
In short, at the RD phase, Information Support documents are a rather malicious vestige, since formally they should be, but there is nothing special to fill them with.
Software (software). Everyone's favorite piece of project documentation. Yes, if only because it is only one document! And then, everyone understands what needs to be written there. But I, nevertheless, will repeat.
In this document, we should tell you what software tools are used to execute the algorithms described in the ML that process the information described in the IO. That is, there is no need to duplicate information from other sections here. Here the architecture of the system is given, the rationale for the selected software technologies, their description (all sorts of system things: programming languages, frameworks, operating systems, etc.). Also in this document, we describe how information processing tools are organized (message queues, storages, backup tools, accessibility solutions, all kinds of application pools, etc.). The standard has detailed description the contents of this document, which will be understood by any specialist.
Technical support (TO). No less beloved by all part of the project documentation. The rosy picture is overshadowed only by the abundance of documents that need to be developed. In total, according to the standard, 22 documents are required to be developed, 9 of them are at the TP stage.
The fact is that the standard provides for a description of all technical support, including computer hardware and networks, engineering systems, and even the building part (if necessary). And this economy is regulated by a huge number of standards and normative acts, is coordinated in different organizations and therefore it is more convenient to break everything up into parts and coordinate (edit) in parts. At the same time, the standard allows you to combine some documents with each other, which makes sense if one person agrees on the whole bunch.
Do not forget also that a set of quality standards implies the accounting and storage of technical documents, and our "booklets" at the customer's site may be distributed in different archives, depending on the subject of the description. This is another argument in favor of splitting the documentation.
Organizational support (OS). Having suppressed in myself the desire, normal for a techie, to skip this section as soon as possible, on the contrary, I will consider it in more detail. Since, colleagues, recently there have been some bad trends in projects that require clarification in this particular section.
At the TP stage, the section contains only one document " Description of the organizational structure”, in which we must tell the customer what he should prepare for in terms of changing the organizational structure. Suddenly you need to organize a new department to operate your system, introduce new positions, etc.
At the RD stage, there are other, more interesting documents that I would like to consider separately.
User guide. Comments are unnecessary, I think.
Methodology (technology) of computer-aided design. In this document, if necessary, you can place a description of the software build process, version control, testing, etc. But this is if in the TOR the customer wants to personally assemble the software. If he does not require this (and does not pay for it), then all your internal kitchen is not his business, and this document does not need to be done.
Technological instruction. In connection with the fashion for the formalization of business processes, a cunning customer sometimes seeks to shove the regulations of the operation service into this document. So, there is no need to do this.
Description of business processes, role and job descriptions, work regulations - all this is an ORD, that is, organizational and administrative documentation. Which is a product of a consulting project, which, as far as I understand, you did not buy. And they bought a technical project from you and technical documentation for it.
The technological instruction is a layer between the ORD and the user manual. The RP describes in detail how you need to do certain actions in the system. The technology manual says what kind actions must be performed in certain cases related to the operation of the system. Roughly speaking, a technological instruction is a brief digest of RP for a specific position or role. If the customer does not have roles formed or he wants you to create roles and requirements for positions yourself, include the most basic roles in the document, for example: operator, senior operator, administrator. Customer comments on the topic, “but we don’t like it” or “but we don’t like it” should be accompanied by a list of roles and a description official duties. Because business processes do not set. We are these business processes we automate.
I will write about the described rake separately, with colorful examples, since this is repeated not for the first time in various sectors of the “national economy”.
Description of the technological process of data processing (including teleprocessing). A miserable rudiment of the cave age, when there were specially dedicated "Computer Operators" who fed punched cards to the machine and packed the printout of the result in an envelope. This guide is for them. What to write in it in the 21st century - I can’t tell you for sure. Get out yourself. The best thing is to just forget about this document.
Whole System Solutions (OR). The standard provides for 17 documents of the OR section. Firstly, these are almost all documents of the preliminary phase of the Preliminary Design. Secondly, these are all kinds of estimates, calculations and brief description automated functions. That is, information for people not from the main IT production, but for support staff - managers, estimators, procurement specialists, economists, etc.
And thirdly, the PR includes a mega-document called “Explanatory Note to the Technical Project”, which, by design, is a kind of Executive Summary, but in fact, many designers shove all the useful content of the TP stage into it. Such a radical approach can be justified and even mutually beneficial for both the customer and the contractor, but in certain cases.
Options for using GOST 34
- Full and exact adherence to the standard. Naturally, no one will voluntarily write such a cloud of documents. Therefore, a complete set of documents is prepared only at the urgent request of the customer, which he enshrined in the TOR and also pressed down on top of the contract. In this case, you need to understand everything literally and give the customer physical "books" on which the names of the documents from Table 2 of GOST 34.201-89 will appear, with the exception of absolutely unnecessary ones, the list of which you must definitely discuss and fix in writing. The content of the documents must also, without any imagination, comply with RD 50-34.698-90, up to the title of the sections. In order for the customer's brain to explode, sometimes a large system is divided into subsystems, and separate project documentation is issued for each subsystem. It looks intimidating and is not subject to normal control with the help of the earthly mind. Especially in terms of subsystem integration. This greatly simplifies acceptance. The main thing is that you yourself do not get confused and that your system still works as it should.
- We just love GOSTs. In serious big companies love standards. Because they help people understand each other better. If your customer is noticed in the love of order and standardization, try to adhere to the standard GOST ideology when developing documents, even if this is not required by the TOR. You will be better understood and approved by the coordinating specialists, and you yourself will not forget to include in the documentation important information, you will better see the target structure of documents, plan the work on writing them more accurately and save yourself and your colleagues a lot of nerves and money.
- We don't care about documentation, as long as everything works. Disappearing view of an irresponsible customer. A similar view of the documentation can still be found among small and poor customers, as well as in the authoritarian "idiotocracies" left over from the time of perestroika, where the boss is surrounded by true friends - directors, and all issues are resolved in personal conversations. In such conditions, you are free to forget about documentation in general, but it’s better, all the same, not to shoot down the sight and at least schematically fill the documentation with content. If not to this customer, then pass (sell) to the next one.
Conclusion
This article was about our GOSTs for documenting automated control systems. GOSTs are old, but, as it turned out, they are still very useful in the economy. Aside from some obvious rudiments, the documentation structure has the properties of completeness and consistency, and following the standard removes many design risks that we may not have guessed at first.
I hope that the material presented was useful to you, or at least interesting. Boring as it may seem, documenting is an important and responsible job, where accuracy is just as important as when writing good code. Write good papers, colleagues! And I'm on next week I’m going on two business trips in a row, so I can’t guarantee the publication of new materials (I don’t have a gas pocket, I’m writing from my head).
M. Ostrogorsky, 2008
In order to successfully apply GOST 34, it is necessary to understand how, from the point of view of this set of standards, an automated system is arranged. Otherwise, we will not see anything in the guests except a long list of documents with mysterious names, and the requirements for their content will once again convince us that there is a lot of sadness in many wisdom. Therefore, before discussing the documents themselves, we must understand what constitutes the subject of documentation.
Automated system, its functions and tasks
Definition of an automated system
GOST 34.003-90 contains the following definition of an automated system: a system consisting of personnel and a set of means for automating its activities, implementing information technology for performing established functions. What does this definition actually mean? You can understand this only by reading the other definitions of this standard and comparing them with each other. What are we going to do now.
Activity goals
An automated system can only exist where there are personnel involved in certain activities. As a rule, we are talking about activities, the results of which are useful to someone, regardless of the tools used. For example, I apply to the theater box office for a ticket, and it will suit me perfectly if the cashier writes it out to me with a pen on the form, if only they would let me into the hall on it. The cashier, by and large, also does not care how to make a ticket. She'll be fine with any method, as long as it's not too laborious and gives her the opportunity to sell me a ticket. In other words, we have a common goal with her. GOST 34.003-90 uses the term purpose of activity. Whenever the next spectator moves away from the window with a ticket in his hands, and the theater becomes a little richer, this goal of activity is achieved.
Functions of the automated system
There can be (and, as a rule, there are) several goals of activity. Any useful result outside the activity itself can be considered its goal. So, if the cashier not only sells the ticket, but also prepares a sales report for the authorities at the end of the working day, compiling a daily report can be considered as another activity goal.
If we put a computer and a printer on the cashier's desk, and the cashier's boss issues an order for her to type tickets and reports in a text editor and print them on the printer, then we get an automated system. According to modern ideas, it is very primitive, formally it will satisfy the Gostov definition. Please note that the goals of the activity as a result of the introduction of an automated system have not changed, only the way to achieve them has changed. What used to be done “just like that” is now done within the framework of an automated system. The set of actions of an automated system aimed at achieving a specific goal, according to GOST 34.003-90, is called its function. Note that no matter how you look at it, the staff is considered part of the system.
The function of an automated system is a fundamental concept in GOST 34. An automated system is considered, first of all, as the sum of its functions and only then as a bunch of “software” and “hardware”. The most important thing is what the system does, and what it consists of is secondary.
The foregoing could lead the reader to the conclusion that each goal of activity in an automated system corresponds to one and only one function. Such a system is easy to imagine, but the practice is more varied. On the one hand, activities are not always fully automated. Some goals, even after the introduction of an automated system, have to be achieved manually. On the other hand, since the same result under different conditions can be achieved different ways, several functions can be directed to one purpose of activity in an automated system, for example, selling a ticket at the box office and selling a ticket on the Internet. In addition, any automated system requires certain maintenance, so we have to introduce the concept of an auxiliary function. A typical example is backing up data.
Tasks of the automated system
In the general case, when performing a function, part of the work is done by the staff, and part of the work is done by the equipment, for example, the ticket is printed automatically, and the cashier issues it manually to the buyer. The sequence of automatic (sic) actions, leading to a result of a given type, in GOST 34.003-90 is called task.
Here the definition of the problem is quoted not quite exactly, but for now this will be enough for us, in the end, it is not shameful for anyone to read the standard on their own. It is important that the task is the most clearly formalized part of the automated activity. One can imagine a function performed completely automatically, such as the backup mentioned above. In this case, the function is reduced to one task.
The same task can be solved by performing different functions. For example, if an automated system has several functions for selling a ticket, then the execution of each of them may at some point require the ticket to be printed.
The composition of the automated system
Subsystems
If the automated system is sufficiently complex, it is divided into subsystems. What does it mean, quite complex, hard enough to say. Systems theory describes different levels and criteria of complexity. In practice, the need to select several subsystems in an automated system is often caused by organizational and financial reasons, for example, subsystems are developed and put into operation sequentially.
Although in GOST 34 the term subsystem is used repeatedly, there seems to be no formal definition of this concept. Experience suggests that a subsystem is a part of an automated system that also meets the definition of an automated system, in particular, has full-fledged functions.
Returning to the ticketing example, we can decide that the automated system consists of two subsystems: the ticketing subsystem and the daily reporting subsystem. Let's just agree for greater clarity that the cashier types the tickets in a text editor, and the reports in spreadsheets.
Components
The selection of the goals of the activity, the functions of the automated system and, if necessary, its subsystems is largely subjective and is made dependent on the point of view of the subject who decided to do this. If a certain result is important in the context of the problem being solved, we can consider it a goal, otherwise we can ignore it. We will also divide the automated system into subsystems in the way that is convenient for us, as long as our decisions do not contradict the content of this concept.
Components are parts from which we build an automated system in objective reality. The system physically consists of its components, so the division of an automated system into components is the most objective.
We purchase, mount and connect each component (if it is equipment), install it (if it is a program) and maintain it separately from other components. We bought and put a computer on the table - this is a component. We developed a special text editor for typing tickets - another component. We downloaded free spreadsheets from the Internet - again a component. And even the cashier herself is in some way also a component of an automated system.
The component-by-component composition of an automated system is very important from the point of view of its documentation, since technical documentation for the system as such and for components are handled differently. Generally speaking, it should be developed different people, and it is issued according to different standards depending on the type of component.
Types of collateral
One of the most difficult concepts for a novice user of GOST 34 is type of collateral. What kind of security is this? Can you see or feel it? Sell or buy?
Each type of security combines components or technical solutions of a certain nature. GOST 34 mentions a lot different types We will not describe each of them sequentially here, but list only the most noticeable:
- information support - all data and metadata with which the system works;
- software - all programs that are part of the system;
- technical support - all technical means (in other words, equipment, apparatus) that are part of the system.
Again, these are not all types of collateral. We cannot even confidently say that they are the most important. For example, for automated process control systems (APCS) great value has metrological support. Many automated systems require complex mathematical and linguistic support. But to imagine an automated system that would be completely devoid of one of the three types of support listed above is difficult (exercise: try it).
Introduction
In the modern world, dozens and hundreds of different programs, applications, information systems appear every day. They can be developed for the public or commercial sector, as well as for ordinary users. 90% of all users do not read the documentation, consider it boring, boring and uninteresting, and open the user manual only when something does not work out or it is completely impossible to figure it out without instructions. It is now common to build a user interface in such a way that it is intuitive, and the user can understand the system without resorting to reading lengthy manuals. However, when working with large customers, it is almost always necessary to submit a certain package of documents - manuals, instructions, design solutions, drawn up in accordance with GOST.
When you first encounter writing documentation in accordance with GOST, you come to a stupor and complete shock, since these GOSTs are “the sea” and how and what to write on them becomes unclear.
This article discusses GOSTs for writing documentation and their main points.
What are GOSTs?
First you need to figure out what GOSTs are. Everyone just knows that GOST is something that was developed under the Union and there are simply an infinite number of them. I hasten to reassure you that there are not so many GOSTs for the IT sphere, and all of them, despite their time of creation, have not lost their relevance.
First of all, standards for writing documentation are divided into two types:
- International standards (ISO, IEEE Std);
- Russian or Soviet GOSTs.
International Standards
International standards are used to develop international level documentation. As a rule, they are not free, as they are not developed by government organizations, but, unlike ours, they were developed quite recently. Topic international standards very broad, so it will be covered in another article. Several standards are immediately touched upon, which are closely related to writing documentation.
List of main international standards for writing documentation:
- IEEE Std 1063-2001 "IEEE Standard for Software User Documentation" - a standard for writing a user manual;
- IEEE Std 1016-1998 "IEEE Recommended Practice for Software Design Descriptions" - a standard for writing a technical description of a program;
- ISO/IEC FDIS 18019:2004 "Guidelines for the design and preparation of user documentation for application software" is another standard for writing a user manual. This document has a large number of examples. So to say, it's more like a guide to writing a user manual. Beginners will be especially useful;
- ISO/IEC 26514:2008 "Requirements for designers and developers of user documentation" is another standard for designers and developers of user documentation.
In fact, there are a lot of international standards, and each country has its own, since the same standard may not always suit both European and Asian companies.
Russian standards
Russian standards are developed at the state level. They are all absolutely free and each of them is easy to find on the Internet. To write the documentation for the program, two series of GOSTs 19 and 34 are used. It is about them that we will discuss further.
What is the difference between GOSTs of series 19 and 34?
The first question that arises is how, in general, these GOSTs 19 and 34 differ from each other.
In GOST 19.781-90 “Unified system of program documentation. Software for information processing systems. Terms and definitions” definitions are given:
- Program - data intended to control specific components of an information processing system in order to implement a specific algorithm.
- Software - a set of programs of the information processing system and program documents necessary for the operation of these programs.
In GOST 34.003-90 “Information technology. Set of standards for automated systems. Automated systems. Terms and definitions" definition is indicated:
- Automated system (AS) - a system consisting of personnel and a set of means for automating its activities, implementing information technology for performing established functions.
Depending on the type of activity, for example, the following types of AS are distinguished: automated control systems (ACS), computer-aided design systems (CAD), automated systems scientific research(ASNI) and others.
Depending on the type of controlled object (process), ACS is divided, for example, into: ACS for technological processes (APCS), ACS for enterprises (APCS), etc.
GOST 34 also makes a division into types of NPP support:
- Organizational;
- methodical;
- Technical;
- Mathematical;
- Software;
- Informational;
- Linguistic;
- legal;
- Ergonomic.
As a result, an automated system is not a program, but a complex of types of support, among which there is also software. AS, as a rule, carries an organizational solution for a specific user and customer, and the Program can be created and replicated for a large number of users without being tied to any enterprise.
Therefore, if you are developing documentation for a program that you created for a specific enterprise, then your GOST 34. If you are writing documents for a mass program, then your GOST 19.
GOST 34
The GOST 34 series (GOST 34.xxx Information Technology Standards) consists of:
- GOST 34.201-89 Types, completeness and designations of documents when creating automated systems - this standard establishes the types, name, completeness and numbers of documents. It is one of the main documents of the GOST 34 series. In fact, this is a basic document, so beginners need to familiarize themselves with it first.
- GOST 34.320-96 Concepts and terminology for the conceptual scheme and information base- This International Standard establishes the basic concepts and terms of conceptual schemas and infobases, covering the development, description and application of conceptual schemas and infobases, manipulation of information, and description and implementation of the information process. The standard defines the role of the conceptual schema. The provisions set forth in it are advisory in nature and can be used to evaluate database management systems (DBMS). This document does not describe specific methods for using the conceptual schema support tools. The conceptual schema languages described in the standard should not be considered standard.
- GOST 34.321-96 Information technologies. Database standards system. Management Reference Model - This document establishes a data management reference model.
The reference model defines common terminology and concepts related to information systems data. Such terms are used to define the services provided by database management systems or data dictionary systems.
The reference model does not consider protocols for managing data.
The scope of the reference model includes processes that deal with the management of persistent data and its interaction with processes that differ from the requirements of a particular information system, as well as general data management services, to define, store, search, update, enter, copy, restore and transfer data. - GOST 34.601-90 Automated systems. Stages of creation - the standard establishes the stages and stages of creating an AU.
- GOST 34.602-89 Terms of reference for the creation of an automated system (Instead of GOST 24.201-85) - establishes the composition, content, rules for processing the document "Terms of Reference for the creation (development or modernization) of the system."
This document is one of the frequently used documents of the GOST 34 series. When developing TOR for this GOST, other standards should be kept in mind, even if this document does not contain references to these standards. - GOST 34.603-92 Information technology. Types of tests of automated systems - the standard establishes the types of tests of the AU autonomous, integrated, acceptance tests and pilot operation) and general requirements for their implementation.
- RD 50-34.698-90 Automated systems. Requirements for the content of documents is one of the most important documents of 34 GOST, since it is in it that the content of almost all documents is described, as well as a description of each item in the document.
- GOST R ISO/IEC 8824-3-2002 Information technology. Abstract Syntax Notation Version One - This International Standard is part of Abstract Syntax Notation Version 1 (ASN.1) and establishes a notation for the specification of user-defined constraints and table constraints.
- GOST R ISO/IEC 10746-3-2001 Data management and open distributed processing.
In this standard:- defines how open distributed processing (ODP) systems are specified using concepts introduced in GOST R ISO/IEC 10746-2;
- the characteristics by which the systems are classified as ODP systems are identified.
The standard establishes a framework for coordinating the development of standards for ODP systems.
- GOST R ISO / IEC 15271-02 Software life cycle processes - this GOST is needed more, in my opinion, for analysts when designing and modeling the AU.
This document is useful, from my point of view, for purely educational purposes. - GOST R ISO/IEC 15910-2002 Software tool user documentation creation process - defines the minimum required process for creating all types of user documentation for a software tool that has a user interface. These types cover printed documentation (eg, user guides and quick reference cards), online (online) documentation, help text ("helps"), and online documentation systems.
So, based on everything written above, it is clear that the main documents in 34 GOST 3: GOST 34.201-89, RD 50-34.698-90 and GOST 34.602-89.
When developing a package of documentation, for starters, you need to open GOST 34.201-89 and select the stage of creation Draft design, Technical design and Working documentation. Next, you should select documents for development that correspond to the stage of creation.
List of documents 34 GOST
| Stage creation |
Title of the document | The code | Part project |
Attached laziness to project but-estimate noah dock cop tions |
Attached laziness to exploiting tation noah up cumen tations |
Additional instructions |
| EP | Draft design sheet | EP* | OR | — | — | — |
| Explanatory note To the draft |
P1 | OR | — | — | — | |
| EP, TP | Organization chart | SO | OR | — | — | It is allowed to include in the document P3 or PV |
| Structural scheme of the complex technical means |
C1* | THEN | X | — | ||
| Functional structure diagram | C2* | OR | — | — | When developing documents CO, C1, C2, C3 at the stage of ES, it is allowed to include them in the document P1 | |
specialized (new) technical means |
AT 9 | THEN | X | — | During development at the TP stage allowed to include to document P2 |
|
| Automation scheme | С3* | THEN | X | — | — | |
| Terms of reference for development specialized (new) technical means |
— | THEN | — | — | The project does not include | |
| TP | Development tasks sanitary and other sections project related with the creation of a system |
— | THEN | X | — | The project does not include |
| Technical design sheet | TP* | OR | — | — | — | |
| List of purchased products | VP* | OR | — | — | — | |
| List of input signals and data |
IN 1 | AND ABOUT | — | — | — | |
| List of output signals (documents) |
IN 2 | AND ABOUT | — | — | — | |
| List of development tasks construction, electrical, sanitary and other sections project related with the creation of a system |
AT 3 | THEN | X | — | It is allowed to include in the P2 document | |
| Explanatory note to the technical project |
P2 | OR | — | — | Includes an action plan preparing the object for commissioning systems in operation |
|
| Description of automated functions |
P3 | OR | — | — | — | |
| Description of the task setting (set of tasks) |
P4 | OR | — | — | It is allowed to include in P2 or P3 documents |
|
| Description of information providing a system |
P5 | AND ABOUT | — | — | — | |
| Description of the organization information base |
P6 | AND ABOUT | — | — | — | |
| TP | Description of classification systems and coding |
P7 | AND ABOUT | — | — | — |
| Array description information |
P8 | AND ABOUT | — | — | — | |
| Description of the complex technical means |
P9 | THEN | — | — | For a task, it is allowed to include in document 46 in accordance with GOST 19.101 | |
| Description of the software securing |
PA | ON | — | — | — | |
| Description of the algorithm (design procedure) |
PB | MO | — | — | It is allowed to include in documents P2, P3 or P4 | |
| Description of organizational structures |
PV | OO | — | — | — | |
| Location plan | C8 | THEN | X | — | It is allowed to include in the P9 document | |
| List of equipment and materials |
— | THEN | X | — | — | |
| Local budget calculation | B2 | OR | X | — | — | |
| TP, RD | Project evaluation system reliability |
B1 | OR | — | — | — |
| Document form drawing (video frame) |
C9 | AND ABOUT | — | X | At the stage of TP it is allowed include in documents P4 or P5 |
|
| RD | List of holders originals |
DP* | OR | — | — | — |
| Statement of operational documents |
ED* | OR | — | X | — | |
| Hardware Specification | AT 4 | THEN | X | — | — | |
| Requirements sheet in materials |
AT 5 | THEN | X | — | — | |
| Statement of machine media information |
VM* | AND ABOUT | — | X | — | |
| Input array | AT 6 | AND ABOUT | — | X | — | |
| RD | Database directory | AT 7 | AND ABOUT | — | X | — |
| Composition of the output (messages) |
AT 8 | AND ABOUT | — | X | — | |
| Local estimates | B3 | OR | X | — | — | |
| Methodology (technology) automated design |
I1 | OO | — | X | — | |
| Technological instruction | AND 2 | OO | — | X | — | |
| User guide | I3 | OO | — | X | — | |
| Instructions for the formation and database management (data set) |
I4 | AND ABOUT | — | X | — | |
| Instruction manual for KTS | IE | THEN | — | X | — | |
| Connection diagram of external wiring | С4* | THEN | X | — | It is allowed to perform in tables |
|
| Wiring diagram external postings |
С5* | THEN | X | — | Also | |
| Table of connections and connections | C6 | THEN | X | — | — | |
| System division diagram (structural) |
E1* | THEN | — | — | — | |
| General view drawing | IN* | THEN | X | — | — | |
| Installation drawing of technical means | SA | THEN | X | — | — | |
| circuit diagram | Sat | THEN | X | — | — | |
| Structural scheme of the complex technical means |
C1* | THEN | X | — | — | |
| Layout of equipment and wiring | C7 | THEN | X | — | — | |
| Description of technological processing process data (including teleworking) |
PG | OO | — | X | — | |
| General description of the system | PD | OR | — | X | — | |
| Test program and methodology (components, complexes of automation equipment, subsystems, systems) |
PM* | OR | — | — | — | |
| Form | FD* | OR | — | X | — | |
| The passport | PS* | OR | — | X | — | |
| *Documents whose code is set in accordance with the requirements of ESKD standards | ||||||
Table note:
- The following designations are accepted in the table:
- EP - preliminary design;
- TP - technical project;
- RD - working documentation;
- OR - system-wide solutions;
- OO - solutions for organizational support;
- TO - solutions for technical support;
- IO - solutions for information support;
- Software - software solutions;
- MO - software solutions.
- Sign X - indicates belonging to the design estimates or operational documentation.
- The nomenclature of documents of the same name is established depending on the design decisions adopted when creating the system.
When the list of documents is determined, then in RD 50-34.698-90 you should find the selected documents and develop them strictly according to the indicated points. All items of content that are indicated must be in the document.
If the Terms of Reference are being developed, then immediately you need to open GOST 34.602-89 and develop the TOR strictly according to the points.
GOST 19
A series of GOSTs 19 (GOST 19.xxx Unified System for Program Documentation (ESPD)) consists of:
- GOST 19.001-77 General provisions - too general document, it is of no practical use. Therefore, it can be skipped.
- GOST 19781-90 Terms and definitions - good list definitions in the field of software for information processing systems. It contains nothing more than definitions.
- GOST 19.101-77 Types of programs and policy documents - one of the main documents of 19 GOST. It is with him that you should start working with GOST 19, since it contains a complete list and designations of GOST documents.
List of documents 19 GOST
| The code | Type of document | Development stages | |||
| Sketchy project |
Technical project |
working draft | |||
| component | complex | ||||
| — | Specification | — | — | ||
| 05 | List of original holders | — | — | — | |
| 12 | Program text | — | — | ||
| 13 | Program description | — | — | ||
| 20 | Statement of operational documents | — | — | ||
| 30 | Form | — | — | ||
| 31 | Application Description | — | — | ||
| 32 | System Programmer's Guide | — | — | ||
| 33 | Programmer's Guide | — | — | ||
| 34 | Operator's manual | — | — | ||
| 35 | Language Description | — | — | ||
| 46 | Technical guide service |
— | — | ||
| 51 | Test program and methodology | — | — | ||
| 81 | Explanatory note | — | — | ||
| 90-99 | Other documents | ||||
Legend:
- the document is required;
- a document mandatory for components that have independent use;
- the need to draw up a document is determined at the stage of development and approval of the terms of reference;
- - the document is not compiled.
- GOST 19.102-77 Development stages - contains a description of the development stages. Useful for educational purposes. In my opinion, there is no particular practical benefit.
- GOST 19.103-77 Designations of programs and program documents - contains a description of assigning a number (code) to a document. Even after reading this GOST, there are a lot of questions about how to assign this same number to a document.
- GOST 19.104-78 Main inscriptions - establishes the forms, sizes, location and procedure for filling in the main inscriptions of the approval sheet and the title page in program documents provided for by the ESPD standards, regardless of how they are performed. Since the documents of 19 GOST are drawn up in frames, this document is very important.
- GOST 19.105-78 General requirements for program documents - establishes general requirements for the design of program documents. The requirements are too general. As a rule, this GOST is almost never used to develop a document, since there is enough special GOST for the document, but for general knowledge it is still better to look at this GOST once.
- GOST 19.106-78 Requirements for printed program documents - contains requirements for the design of all documents of 19 GOST.
- GOST 19.201-78 Terms of reference, requirements for content and design - establishes the procedure for the construction and execution of terms of reference for the development of a program or software product.
Clauses of TK 34 GOST and 19 GOST are different.
- GOST 19.601-78 General rules for duplication, accounting and storage - general rules duplication, circulation, accounting and storage of program documents. In GOST, several paragraphs describe how to make sure that documents are not lost.
- GOST 19.602-78 Rules for duplication, accounting and storage of program documents, performed by printing. Method - addition to GOST 19.601-78.
- GOST 19.603-78 General rules for making changes - establishes general rules for making changes to program documents. In fact, it describes a long bureaucratic algorithm for making changes to documents.
- GOST 19.604-78 Rules for making changes to printed program documents - describes the procedure for working and filling out from the Change Registration Sheet.
A list of specialized GOSTs, that is, each of them describes the content and requirements for a particular document:
- GOST 19.202-78 Specification. Requirements for content and design;
- GOST 19.301-79 Program and test procedure. Requirements for content and design;
- GOST 19.401-78 Program text. Requirements for content and design;
- GOST 19.402-78 Description of the program;
- GOST 19.403-79 List of original holders;
- GOST 19.404-79 Explanatory note. Requirements for content and design;
- GOST 19.501-78 Form. Requirements for content and design;
- GOST 19.502-78 Application description. Requirements for content and design;
- GOST 19.503-79 System programmer's guide. Requirements for content and design;
- GOST 19.504-79 Programmer's guide. Requirements for content and design;
- GOST 19.505-79 Operator's manual. Requirements for content and design;
- GOST 19.506-79 Language description. Requirements for content and design;
- GOST 19.507-79 Statement of operational documents;
- GOST 19.508-79 Maintenance manual. Requirements for content and design.
The procedure for working with 19 GOST:
- In GOST 19.101-77, select a document and its code according to the development stage.
- According to GOST 19.103-77, assign a number to the document.
- Then, according to GOSTs 19.104-78 and 19.106-78, draw up a document.
- From a specialized list of GOSTs, you should choose the one that corresponds to the document being developed.
Conclusion
GOST - it's not scary and easy! The main thing is to understand what needs to be written and what GOST is used for this. Our main GOSTs 19 and 34 for writing documentation are very old, but still relevant to this day. Writing documentation according to the standard removes many issues between the contractor and the customer. Hence, it saves time and money.
Date of introduction 01.01.92
This standard applies to automated systems (AS) used in different types activities (research, design, management, etc.), including their combinations created in organizations, associations and enterprises (hereinafter - organizations).
The standard establishes the stages and stages of creating an AS. Appendix 1 shows the content of the work at each stage.
1. General Provisions
2. Stages and stages of creating AS
Annex 1 (informative)
Annex 2 (informative)
1. GENERAL PROVISIONS
1.1. is a set of ordered in time, interconnected, united in stages and stages of work, the implementation of which is necessary and sufficient to create an AU that meets the specified requirements.
1.2. The stages and stages of the creation of AS are distinguished as parts of the creation process for reasons of rational planning and organization of work, ending with a given result.
1.3. Work on the development of the AU is carried out according to the stages and stages used to create the AU.
1.4. The composition and rules for performing work at the stages and stages established by this standard are determined in the relevant documentation of organizations involved in the creation of specific types of nuclear power plants.
The list of organizations involved in the creation of the AU is given in Appendix 2.
2. STAGES AND STAGES OF CREATING AS
2.1. The stages and stages of creating an AS in the general case are given in the table.
| Stages | Stages of work |
|---|---|
| 1. Formation of requirements for the AU | 1.1. Inspection of the object and justification for the need to create an AU |
| 1.2. Formation of user requirements for the AU | |
| 1.3. Registration of a report on the work performed and an application for the development of an AU (tactical and technical specifications) | |
| 2. Development of the AU concept | 2.1. Studying the object |
| 2.2. Carrying out the necessary research work | |
| 2.3. Development of options for the concept of the AU and the choice of a variant of the concept of the AU that meets the requirements of the user | |
| 2.4. Preparation of a report on the work performed | |
| 3. Terms of reference | 3.1. Development and approval of terms of reference for the creation of the AU |
| 4. Draft design | 4.1. Development of preliminary design solutions for the system and its parts |
| 4.2. Development of documentation for the AU and its parts | |
| 5. Technical project | 5.1. Development of design solutions for the system and its parts |
| 5.2. Development of documentation for the AU and its parts | |
| 5.3. Development and execution of documentation for the supply of products for the acquisition of nuclear power plants and (or) technical requirements (technical specifications) for their development | |
| 5.4. Development of design tasks in adjacent parts of the project of the automation object | |
| 6. Working documentation | 6.1. Development of working documentation for the system and its parts |
| 6.2. Development or adaptation of programs | |
| 7. Input and action | 7.1. Preparing the automation object for putting the AU into operation |
| 7.2. Staff training | |
| 7.3. Completion of the AU with supplied products (software and hardware, software and hardware systems, information products) | |
| 7.4. Construction and installation works | |
| 7.5. Commissioning works | |
| 7.6. Carrying out preliminary tests | |
| 7.7. Conducting trial operation | |
| 7.8. Conducting acceptance tests | |
| 8. Accompanying speakers | 8.1. Performing work in accordance with warranty obligations |
| 8.2. Post-warranty service |
2.2. Stages and stages performed by organizations - participants in the creation of nuclear power plants are established in contracts and terms of reference based on this standard.
It is allowed to exclude the stage "Draft design" and separate stages of work at all stages, to combine the stages "Technical design" and "Detailed documentation" into one stage "Technical design". Depending on the specifics of the AS being created and the conditions for their creation, it is allowed to perform individual stages of work until the completion of the previous stages, the parallel execution of work stages in time, the inclusion of new stages of work.
APPENDIX 1. Reference
1. At stage 1.1 "Survey of the object and justification of the need to create an NPP" in the general case, the following is carried out:
- collection of data on the automation object and ongoing activities;
- assessment of the quality of the functioning of the object and the types of activities carried out, identification of problems that can be solved by means of automation;
- assessment (technical, economic, social, etc.) of the feasibility of creating a nuclear power plant.
2. At stage 1.2 "formation of user requirements for the AU" is carried out:
- preparation of initial data for the formation of requirements for the AU (characteristics of the automation object, description of the requirements for the system, limits on the allowable costs of development, commissioning and operation, the effect expected from the system, the conditions for the creation and operation of the system);
- formulation and execution of user requirements for the AU.
3. At stage 1.3 "Filing up a report on the work performed and an application for the development of an AU (tactical and technical assignment)", a report on the work performed at this stage is drawn up and an application for the development of an AU (tactical and technical assignment) or another document replacing it with similar content.
4. At stages 2.1 "Studying the object" and 2.2 "Conducting the necessary research work", the developer organization conducts a detailed study of the automation object and the necessary research work (R&D) related to finding ways and assessing the possibility of implementing user requirements, draw up and approve research reports.
5. At stage 2.3 "Development of options for the concept of the AU and the choice of a variant of the concept of the AU that meets the requirements of the user", in the general case, the development is carried out alternatives concepts of the created AS and plans for their implementation; evaluation necessary resources for their implementation and operation; an assessment of the advantages and disadvantages of each option; comparison of user requirements and characteristics of the proposed system and selection the best option; determination of the procedure for assessing the quality and conditions for the acceptance of the system; assessment of the effects received from the system.
6. At stage 2.4 "Formulation of the report on the work performed" prepare and draw up a report containing a description of the work performed at the stage, a description and justification of the proposed version of the system concept.
7. At stage 3.1 "Development and approval of terms of reference for the creation of the NPP", the development, execution, coordination and approval of the terms of reference for the NPP and, if necessary, the terms of reference for parts of the NPP are carried out.
8. At stage 4.1 "Development of preliminary design solutions for the system and its parts" determine: the functions of the AU; functions of subsystems, their goals and effects; composition of task complexes and individual tasks; concepts of the information base, its enlarged structure; database management system functions; composition of the computer system; functions and parameters of the main software tools.
9. At stage 5.1 "Development of design solutions for the system and its parts" ensure the development of general solutions for the system and its parts, the functional-algorithmic structure of the system, the functions of personnel and organizational structure, by the structure of technical means, by algorithms for solving problems and by the languages used, by organizing and maintaining an information base, by a system for classifying and coding information, by software.
10. At steps 4.2 and 5.2 " Documentation Development on the NPP and its parts” carry out the development, execution, coordination and approval of documentation in the amount necessary to describe the full set of design decisions made and sufficient for further work on the creation of the NPP. Types of documents - according to GOST 34.201.
11. At stage 5.3 "Development and execution of documentation for the supply of products for completing the NPP and (or) technical requirements (technical specifications) for their development", preparation and execution of documentation for the supply of products for completing the NPP; determination of technical requirements and preparation of technical specifications for the development of products that are not mass-produced.
12. At stage 5.4 "Development of design assignments in adjacent parts of the automation project", they develop, execute, agree and approve design assignments in adjacent parts of the automation object project for construction, electrical, sanitary and other preparatory work related to the creation AS.
13. At stage 6.1 "Development of working documentation for the system and its parts", they develop working documentation containing all the necessary and sufficient information to ensure the implementation of work on putting the NPP into operation and its operation, as well as to maintain the level of operational characteristics (quality) of the system in accordance with the adopted design decisions, its execution, coordination and approval. Types of documents - according to GOST 34.201.
14. At stage 6.2 "Development or adaptation of programs", the development of programs and software tools of the system, the selection, adaptation and (or) binding of purchased software tools, the development of software documentation in accordance with GOST 19.101 are carried out.
15. At stage 7.1 "Preparation of the automation object for putting the AU into operation", work is carried out on the organizational preparation of the automation object for putting the AU into operation, including: implementation of design decisions on the organizational structure of the AU; providing units of the control object with instructive and methodological materials; introduction of information classifiers.
16. At stage 7.2 "Personnel training", personnel are trained and their ability to ensure the functioning of the NPP is checked.
17. At the stage "Packing the NPP with supplied products" ensure the receipt of components of serial and single production, materials and assembly products. Carry out input quality control.
18. At stage 7.4 "Construction and installation work", the following is carried out: construction of specialized buildings (premises) for the placement of technical facilities and NPP personnel; construction of cable channels; performance of works on installation of technical means and communication lines; testing of installed technical means; delivery of technical means for commissioning.
19. At stage 7.5 "Commissioning" carry out offline adjustment of hardware and software, loading information into the database and checking the system of its maintenance; complex adjustment of all means of the system.
20. At stage 7.6 "Conducting preliminary tests" carry out:
- tests of the AU for performance and compliance with the terms of reference in accordance with the program and methodology of preliminary tests;
- troubleshooting and making changes to the documentation for the NPP, including operational documentation in accordance with the test protocol;
- registration of the act of acceptance of the NPP for trial operation.
21. At stage 7.7 "Conducting trial operation", the NPP trial operation is carried out; analysis of the results of NPP trial operation; finalization (if necessary) of the AS software; additional adjustment (if necessary) of technical means of the AU; registration of the certificate of completion of trial operation.
22. At stage 7.8 "Conducting acceptance tests" carry out:
- tests for compliance with the technical specifications in accordance with the program and methodology of acceptance tests;
- analysis of the test results of the AU and the elimination of shortcomings identified during the tests;
- registration of the act of acceptance of the NPP into permanent operation.
23. At stage 8.1 "Performance of work in accordance with warranty obligations", work is carried out to eliminate the shortcomings identified during the operation of the NPP within the established warranty periods, to make the necessary changes to the documentation for the NPP.
24. At stage 8.2 "Post-warranty service" work is carried out on:
- analysis of the functioning of the system;
- identification of deviations of the actual operational characteristics of the NPP from the design values;
- establishing the causes of these deviations;
- elimination of identified deficiencies and ensuring the stability of the operational characteristics of the NPP;
- making the necessary changes to the documentation for the AU.
APPENDIX 2. Reference
LIST OF ORGANIZATIONS PARTICIPATED IN THE CREATION OF THE AU
1. The customer organization (user) for which the AU will be created and which provides financing, acceptance of work and operation of the AU, as well as the performance of individual works to create the AU.
2. Organization-developer, which carries out work on the creation of the AU, presenting to the customer a set of scientific and technical services on different stages and stages of creation, as well as developing and supplying various software and hardware AS.
3. A supplier organization that manufactures and supplies software and hardware on the order of a developer or customer.
4. Organization-general designer of the automation object.
5. Design organizations various parts project of an automation object for construction, electrical, sanitary and other preparatory work related to the creation of the NPP.
6. Construction, installation, adjustment and other organizations.
Notes:
1. Depending on the conditions for the creation of the AU, various combinations of the functions of the customer, developer, supplier and other organizations involved in the creation of the AU are possible.
2. The stages and stages of their work on the creation of the AU are determined on the basis of this standard.
INFORMATION DATA
1. DEVELOPED AND INTRODUCED by the USSR State Committee for Product Quality Management and Standards
DEVELOPERS
Yu.Kh. Vermishev, Dr. tech. sciences; Ya.G. Vilenchik; IN AND. Voropaev, Dr. Sc. sciences; L.M. Seidenberg, Ph.D. tech. sciences; Yu.B. Irz, Ph.D. tech. sciences; V.D. Kostyukov, Ph.D. tech. sciences; M.A. Labutin, cond. tech. sciences; N.P. Leskovskaya; I.S. Mityaev; V.F. Popov (topic leader); S.V. Garshin; A.I. deaf believer; SOUTH. Zhukov, Ph.D. sciences; Z.P. Zadubovskaya; V.G. Ivanov; Yu.I. Karavanov, Ph.D. sciences; A.A. Klochkov; V.Yu. Korolev; IN AND. Makhnach, Ph.D. tech. sciences; S.B. Mikhalev, Dr. tech. sciences; V.N. Petrikevich; V.A. Rakhmanov, Ph.D. economy sciences; A.A. Ratkovich; R.S. Sedegov, Doctor of Economics. sciences; N.V. Stepanchikov; M.S. Surovets; A.V. Flegentov; L.O. Khvilevsky, Ph.D. tech. sciences; VC. Chistov, Ph.D. economy sciences
2. APPROVED AND INTRODUCED BY Decree of the USSR State Committee for Product Quality Management and Standards dated December 29, 1990 No. 3469
