How to write a technical specification example. Purpose and goals of creating the system. Preparation for laboratory work

In this article I tried to consider in detail the problem of developing Technical Specifications. The topic is as old as the problem. But it is still often decided “as it turns out.” As Henry Shaw said, “It’s the little things that worry us most: it’s easier to dodge an elephant than a fly.”

What is this article about?

• In the first part " Development of technical specifications. What is it, why is it needed, where to start and what it should look like? I will try to answer the questions of the topic in detail, consider the structure and purpose of the Terms of Reference, and give some recommendations on the formulation of requirements.
• Second part " Development of technical specifications. How to formulate requirements? will be entirely devoted to identifying and formulating requirements for an information system.

• A commercial organization decided to implement an automated system. It does not have its own IT service and decided to do this: The interested party must develop a Technical Specification and submit it for development third party organization;
• A commercial organization decided to implement an automated system. It has its own IT service. We decided to do this: develop a Technical Specification, then agree on it between the IT service and interested parties, and implement it on our own;
• The government agency decided to start an IT project. Everything here is so murky, a lot of formalities, kickbacks, cuts, etc. I will not consider this option in this article.
• An IT company provides services for the development and/or implementation of automated systems. This is the most difficult case, because you have to work in a variety of conditions:
  • The client has his own specialists with their own views, and they make specific requirements for the Technical Specifications;
  • The terms of reference are developed for in-house developers (the client doesn’t care);
  • The terms of reference are developed for transfer to the contractor (i.e. a group of programmers on staff of the company, or an individual specialist);
  • A misunderstanding arises between the company and the client regarding the result obtained, and the company again and again asks the question: “How should the Technical Specifications be developed?” The last case may seem like a paradox, but it is true.
  • Other, less common options are also possible;

• Why can’t the Technical Specifications always be developed the same way?
• Are there any standards, methods, recommendations? Where can I get them?
• Who should develop the Terms of Reference? Should this person have any special knowledge?
• How to understand whether the Terms of Reference are well written or not?
• At whose expense should it be developed, and is it even necessary?

What is a technical specification?

Yes, there really are GOSTs and standards that attempt to regulate this part of the activity (software development). Once upon a time, all these GOSTs were relevant and actively used. Now there are different opinions about the relevance of these documents. Some argue that GOSTs were developed by very far-sighted people and are still relevant. Others say they are hopelessly outdated. Perhaps someone now thought that the truth was somewhere in the middle. I would answer in the words of Goethe: “They say that between two opposing opinions lies the truth. No way! There is a problem between them." So, there is no truth between these opinions. Because GOSTs do not reveal practical problems modern development, and those who criticize them do not offer an alternative (specific and systemic).

Note that GOST clearly does not even give a definition, it only says: “TK for a nuclear power plant is the main document defining the requirements and procedure for creating (development or modernization - then creation) of an automated system, in accordance with which the development of a nuclear power plant is carried out and its acceptance upon commissioning into action."

If anyone is interested in what GOSTs I’m talking about, here they are:

• GOST 2.114-95 Unified system design documentation. Technical specifications;
• GOST 19.201-78 Unified system of program documentation. Technical specifications. Requirements for content and design;
• GOST 34.602-89 Information technology. A set of standards for automated systems. Terms of reference for the creation of an automated system.

And so, as follows from the definition, the main purpose of the Technical Specification is to formulate the requirements for the object being developed, in our case, for an automated system.

It is the main thing, but the only one. The time has come to get down to the main thing: to put everything “on the shelves”, as promised.

What do you need to know about the requirements? It is necessary to clearly understand that all requirements must be divided by type and properties. Now we will learn how to do this. To separate requirements by type, GOST will help us. The list of types of requirements that is presented there is a good example of what types of requirements should be considered. For example:

• Functionality requirements;
• Security and access rights requirements;
• Requirements for personnel qualifications;
• …. Etc. You can read about them in the mentioned GOST (and below I will also consider them in a little more detail).

I said about the types of requirements, but what about properties? If the types of requirements can be different (depending on the goals of the project), then with properties everything is simpler, there are 3 of them:

1. The requirement must be understandable;
2. The requirement must be specific;
3. The requirement must be test takers;

This concludes the story about what a Technical Specification is and moves on to the main thing: how to formulate requirements. But it's not that fast. There is another extremely important point:

• In what language (in terms of difficulty of understanding) should the technical specification be written?
• Should the specifications be described in it? various functions, algorithms, data types and other technical things?
• What is technical design, which, by the way, is also mentioned in GOSTs, and how is it related to the Technical Specifications?

Technical specifications- this is a document based on requirements formulated in a language that is understandable (ordinary, familiar) to the Customer. In this case, industry terminology that is understandable to the Customer can and should be used. There should be no connections to the specifics of the technical implementation. Those. at the technical specification stage, in principle, it does not matter on which platform these requirements will be implemented. Although there are exceptions. If we are talking about implementing a system based on an already existing software product, then such a connection can take place, but only at the level of screen forms, report forms, etc. The clarification and formulation of requirements, as well as the development of Terms of Reference should be carried out business analyst. And certainly not a programmer (unless he combines these roles, this happens). Those. this person must speak to the Customer in the language of his business.

Technical project - this is a document that is intended for the technical implementation of the requirements formulated in the Terms of Reference. This document describes data structures, triggers and stored procedures, algorithms and other things that will be required technical specialists. The customer does not have to delve into this at all (even such terms may not be clear to him). Technical project does System Architect(combining this role with a programmer is quite normal). Or rather, a group of specialists led by an architect. The larger the project, the more people work on the Terms of Reference.

What do we have in practice? It’s funny to watch when the director is presented with a technical specification for approval, which is replete with technical terminology, descriptions of data types and their values, database structure, etc. He, of course, tries to understand, since he needs to approve, trying to find familiar words between the lines and not lose the chain business requirements. Is this a familiar situation? And how does it end? As a rule, such technical specifications are approved, then implemented, and in 80% of cases, then they do not at all correspond to the fact of the work performed, because they decided to change, redo a lot of things, misunderstood, thought wrong, etc. etc. And then the series about submitting work begins. “But here it’s not what we need,” but “this won’t work for us,” “it’s too complicated,” “it’s inconvenient,” etc. Sound familiar?!! That’s familiar to me, I had to hit the bumps in due time.

So what do we have in practice? But in practice, we have a blurred boundary between the Terms of Reference and the Technical Project. She floats between TK and TP in a variety of manifestations. And that's bad. This happens because the development culture has become weak. This is partly due to the competencies of specialists, partly due to the desire to reduce budgets and deadlines (after all, documentation takes a lot of time - that’s a fact). There is another important factor influencing the use of the Technical Design as a separate document: rapid development rapid development tools, as well as development methodologies. But this is a separate story; I’ll say a few words about it below.

Another small but important point. Sometimes Terms of Reference are called a small piece of requirements, simple and understandable. For example, improve the search for an object based on some conditions, add a column to the report, etc. This approach is quite justified, why complicate life. But it is used not on large projects, but on minor improvements. I would say this is closer to software product maintenance. In this case, the Terms of Reference may also describe specific technical solution implementation of the requirement. For example, “Make such and such a change to such and such an algorithm,” indicating a specific procedure and a specific change for the programmer. This is the case when the boundary between the Terms of Reference and Technical Projects is completely erased, because there is no economic feasibility to inflate paperwork where it is not needed, but a useful document is created. And that's right.

Is technical specification necessary at all? What about the Technical Project?

What about the Technical Project? This document is very useful and has not lost its relevance. Moreover, often you simply cannot do without it. Especially when it comes to outsourcing development work, i.e. on the principle of outsourcing. If you don't do this, you run the risk of learning a lot about what the system you have in mind should look like. Should the Customer become familiar with it? If he wants, why not, but there is no need to insist and approve this document, it will only hold back and interfere with work. It is almost impossible to design a system down to the smallest detail. In this case, you will have to continuously make changes to the Technical Design, which takes a lot of time. And if the organization is heavily bureaucratic, then you will leave all your nerves there. Reducing this kind of design is exactly what modern rapid development methodologies that I mentioned above are all about. By the way, they are all based on the classic XP (extreme programming) - an approach that is already about 20 years old. So make a high-quality Technical Specification that is understandable to the Customer, and use the Technical Design as an internal document for the relationship between the system architect and programmers.

An interesting detail about technical design: some development tools designed on the principle of subject-oriented design (such as 1C and similar) assume that design (meaning the documentation process) is required only in truly complex areas where interaction between entire subsystems is required. In the simplest case, for example, creating a directory or document, only correctly formulated business requirements are enough. This is also evidenced by the business strategy of this platform in terms of training specialists. If you look at the exam card of a specialist (that’s what it’s called, not a “programmer”), you will see that there are only business requirements, and how to implement them in a program language is the specialist’s task. Those. that part of the problem that the Technical Project is intended to solve, the specialist must solve “in his head” (we are talking about tasks of medium complexity), here and now, following certain development and design standards, which again are formed by the 1C company for its platform. Thus, of two specialists whose work results look identical, one can pass the exam, but the other cannot, because flagrantly violated development standards. That is, it is obviously assumed that specialists must have such qualifications that they can design typical tasks independently, without the involvement of system architects. And this approach works.

Let’s continue to study the question: “What requirements should be included in the Terms of Reference?”

Formulation of requirements for the information system. Structure of the Terms of Reference

Like any activity, formulating requirements can (and should) be divided into stages. Everything has its time. This is hard intellectual work. And, if you treat it with insufficient attention, then the result will be appropriate. According to expert estimates, the cost of developing the Terms of Reference can be 30-50%. I am of the same opinion. Although 50 is perhaps too much. After all, the Technical Specification is not yet last document, which must be developed. After all, there must also be technical design. This variation is due to different automation platforms, approaches and technologies used by project teams during development. For example, if we are talking about development in a classical language like C++, then detailed technical design is indispensable. If we are talking about implementing a system on the 1C platform, then the situation with design is somewhat different, as we saw above (although, when developing a system from scratch, it is designed according to the classical scheme).

Despite the fact that the formulation of requirements is the main part of the Technical Specification, and in some cases it becomes the only section of the Technical Specification, you should pay attention to the fact that this is an important document, and it should be drawn up accordingly. Where to start? First of all, you need to start with the content. Write the content and then start expanding it. Personally, I do this: first I sketch out the content, describe the goals, all the introductory information, and then get down to the main part - the formulation of the requirements. Why not the other way around? I don't know, it's more convenient for me. Firstly, this is a much smaller part of the time (compared to the requirements), and secondly, while you are describing all the introductory information, you tune in to the main thing. Well, whoever likes it. Over time, you will develop your own Technical Specification template. To begin with, I recommend taking as content exactly the one described in GOST. It's perfect for content! Then we take and begin to describe each section, not forgetting about the recommendations of following three properties: understandability, specificity and testability. Why do I insist on this so much? More on this in the next section. And now I propose to go through those points of the technical specifications that are recommended in GOST.

1. general information;
2. purpose and goals of creation (development) of the system;
3. characteristics of automation objects;
4. system requirements;
5. composition and content of work to create the system;
6. procedure for control and acceptance of the system;
7. requirements for the composition and content of work to prepare the automation object for putting the system into operation;
8. documentation requirements;
9. development sources.

Section 1. general information.

And so, we have considered all the sections that can be included in the Terms of Reference. “Can” and not “Must” precisely because any document must be developed to achieve a result. Therefore, if it is obvious to you that a particular section will not bring you any closer to the result, then you don’t need it and you don’t need to waste time on it.

But no competent technical specification can do without the main thing: functional requirements. I would like to note that in practice such Technical Specifications occur, and how! There are people who will be able to separate the waters in all sections, describe the general requirements in general terms, and the document turns out to be very weighty, and there are a lot of clever words in it, and even the Customer may like it (that is, he will approve it). But it may not work according to it, i.e. It has little practical use. In most cases, such documents are born when you need to get a lot of money specifically for the Terms of Reference, but it needs to be done quickly and without diving into details. And especially if it is known that the matter will not go further, or completely different people will do it. In general, just to manage the budget, especially the state budget.

In the second article we will talk only about section 4 “System requirements”, and specifically we will formulate requirements for reasons of clarity, specificity and testability.

Why requirements must be clear, specific and testable.

What is a technical specification? How to do it and what is it for? Examples, samples, tips and recommendations.

It would seem how great it is when someone understands you perfectly. You gave out a few phrases and here it is, exactly what you imagined. Unfortunately, it doesn't work that way.

The problem of information perception is eternal. The “broken phone” effect is a common occurrence. But what about if you simply don’t know how to set a task? Yes, this also happens and you need to work with it somehow, but how? To ensure that the results of the tasks you set meet your expectations, write a technical specification.

What is a technical specification

Technical specification (or TOR) is a document that contains the customer’s requirements for the products or services provided by the contractor. In simple words: I want this way and that, so that there are seven mutually perpendicular lines, and also draw some in red, and draw some colorless (I advise you to watch a video about this topic at the end of the material).

Design Bureau

This document can take up either one A4 page or a whole volume, it all depends on the tasks and wishes that are included in it. For example, you can write a technical specification for a small landing page (one-page website) or for complex software with machine learning and other features.

Why do you need technical specifications?

• To assign tasks to performers.
• To describe in detail what you want to get at the end.
• To agree on the order of work.
• To evaluate and accept the work after implementation.
• To...(add your options in the comments).

In fact, there are much more purposes and advantages of the technical specification than in the list above. For me personally, the main task that technical specifications solve is the implementation of what I need with minimal deviations from expectations (my expectations).

Thanks to technical specifications, you can always ask about implementation time, money and compliance with the declared characteristics of the final product or service.

In fact, this is a serious document that is drawn up by the customer and the contractor. To the extent that penalties and obligations of the parties are prescribed. There are a number of GOSTs, read more on Habré.

Development of technical specifications

If we are talking about a “grown-up” game, for example, technical specifications for development mobile application or a website, then this is a separate job for which a lot of money is paid. You attract a person, usually a former or current Chief Technical Officer, and ask him to help you.

Having a beard is optional

Depending on the scope of the project/tasks, this person collects all your “wants” and translates them into technical language, maybe prepares sketches (what it should approximately look like) and gives you the finished document. Next, you hand over this document to the performers (a team within your company or outsourced), agree on money, deadlines, and get to work.

Tip: The CTO should be on your team, otherwise you will most likely miss something during the implementation process. You simply don’t have enough knowledge for everything. Whoever participated in writing the technical specifications checks it.

What does the technical specification consist of?

Everything will depend on the template you choose (a little further I will give some links to templates/examples), but there are basic blocks that are included in the technical specifications:

1. Description of the project/task. We briefly write what the project or task is that needs to be completed.
2. Purpose and goals. What are the goals for the project?
3. Requirements. Design, functions, technologies that are needed.
4. Description of work. What, when and how will be done.
5. Control and acceptance procedure. How the work will be accepted, what can be considered completed.
6. Applications. Sketches, sketches, prototypes.

The cost of work is usually calculated in separate application to the contract, but it happens when the parties specify the amounts in the technical specifications themselves.

Sorry to interrupt reading. Join my telegram channel. Fresh announcements of articles, development of digital products and growth hack, it’s all there. I'm waiting for you! Let's continue...

Examples of technical specifications

Despite the fact that the development of technical specifications is a complex process, it is very interesting. Your task is to recreate the picture of the final result, and then describe it in parts.

An example of one of my terms of reference for updating the Smart TV application. Tasks for more complex and complex products were compiled with the help of colleagues from the technical department. Do not hesitate to ask your teammates for help, involve them in the process as often as possible. And don't forget to give feedback! There is nothing worse than putting effort and time into something without knowing the results. Tell us how the person’s advice was useful in your work, otherwise, it’s a one-sided game.

Terms of reference for the development of an online store

Terms of reference for the development of a mobile application

Terms of reference for the site

Terms of reference for services/updates

If you need more samples, just Google it.

The main recommendation is to do this. The trouble is that mother laziness overcomes everyone and it is not easy to resist it. Gather all your willpower and start writing technical specifications, just write and don’t stop. Don’t worry that it doesn’t work out “perfectly”, I’ll tell you a secret, this never happens. Just write, it will get better and better every time.

This is how it should be

My first rudiments for writing technical specifications began to appear several years ago. I worked with designers and was tasked with creating creatives for advertising campaigns. I wanted it incoherently and it turned into a lot of wasted time and explanations. Over time, the setting of tasks began to turn into some kind of semantic blocks, and then into something like a technical specification.

For example, for the task “Like button on the site”:

1. Description: you need to create a “Like” button on our website.
2. Purpose and goals: user involvement, issuance/rating of materials based on the number of likes.
3. Requirements: such a design (example: a link to something similar), functionality (any user can rate a picture and like it, the site system takes into account the number of likes and changes the output of materials), technology (available on desktop and mobile versions site).
4. Description of work: draw 3 options for button layouts (date of completion: 10/01/17), develop a system for distributing materials based on likes (date: 10/14/17), function testing (date: 10/16/17), release (date: 10/17/17)
5. Acceptance of work: the user presses the like button, the system counts the click, and the delivery of materials changes.
6. Applications: sketches, sketches, examples of projects where a similar function works.

Leave for yourself those sections and parts of the structure that are needed for your tasks. For example, the sixth block “Applications” can be described in functional requirements. Basic advice: one way or another, describe the task according to the structure of the technical specifications. This way, you won’t miss important points and save yourself from unnecessary questions, while making life easier for your colleagues.

Here you go

We looked at what a technical task is and how to do it. Now you have the ability to clearly and clearly set tasks, convey your thoughts to other people and save time on additional explanations. I hope now you know what to do with all this.

The terms of reference are the source material for creating an information system or other product. Therefore, the technical specification (abbreviated as TK) must first of all contain the basic technical requirements for the product and answer the question of what this system should do, how to work and under what conditions.

As a rule, the stage of drawing up technical specifications is preceded by a survey subject area, which ends with the creation of an analytical report. It is the analytical report (or analytical note) that forms the basis of the Terms of Reference document.

If the report can present the customer's requirements in general terms and illustrate them with UML diagrams, the technical specifications should describe in detail all functional and user requirements for the system. The more detailed the technical specifications are, the fewer controversial situations will arise between the customer and the developer during acceptance tests.

Thus, the technical specification is a document that allows both the developer and the customer to present the final product and subsequently check for compliance with the requirements.

The guiding standards for writing technical specifications are GOST 34.602.89 “Technical specifications for the creation of an automated system” and GOST 19.201-78 “Technical specifications. Requirements for content and design." The first standard is intended for developers of automated systems, the second for software(we discussed the difference between these series in the article “What is GOST”).

So, below we present a list and description of the sections that the technical specifications should contain in accordance with GOSTs.

So, the Technical Specifications document should, in fact, reflect all the requirements for the designed product, identified at the stage of analytical research of the automation object.

Based on the table above, we can highlight the main sections of the technical specifications:

• General information about the system (program);
• Purpose, goals and objectives of the system (program);
• System requirements (functional requirements, user requirements, requirements for the system as a whole, etc.);
• Requirements for types of security;
• Documentation requirements;
• Stages and stages of development;
• The procedure for control and acceptance of the system (program).

General information
This section of the Technical Specifications document must contain the full name of the system and all abbreviations that will be used in developing the documentation.

Example:

"IN this document The information system being created is called “Single window of access to educational resources”, abbreviated as SW.
The Single Window for Access to Educational Resources System may be further referred to as the Single Window or the System in this document.”

Also here you should include subsections providing details of the organizations involved in the development (Customer and Contractor).

The subsection “Basis for development” of the Technical Specifications document lists the main documents on the basis of which this work is carried out. For example, for a system commissioned by the Government of a country or another Government body, laws, decrees and regulations of the Government must be specified.

An integral part of the Technical Specifications document should also be a list of terms and abbreviations. It is better to present terms and abbreviations in the form of a table with two columns “Term” and “Full Form”.

Terms and abbreviations are located in alphabetical order. First of all, it is customary to decipher Russian-language terms and abbreviations, then English-language ones.

Purpose and goals of creating the system

This section of the Technical Specification document must contain the purpose and goals of creating the system.

Example:

“The information system “Single Window of Access to Educational Resources” is designed to provide users with complete, prompt and convenient information regarding the education system of the Russian Federation and organizations performing the function of educational institutions.

The main goal of the System is to form a unified information environment and automation of business processes of educational institutions of the Russian Federation.

The creation of the Single Window information system should ensure:

• providing users with a wide range of information resources;
• level up information security;
• increasing the efficiency of educational institutions and departments by optimizing a number of business processes;
• increasing the efficiency of the process of interaction between information systems and services within the department.

The creation of the System will reduce operating costs as a result of increasing the efficiency of the department.”

System requirements

This section of the Technical Specification document is intended to describe the basic functional requirements of the system. This is the most important part of the technical specification, since it will be your main argument in disputes with the Customer during the process of putting the system into operation. Therefore, it is necessary to approach its writing very carefully.

The Terms of Reference document must contain all the requirements identified at the stage of analysis of the automation object. It is best to highlight the main business processes, which should be disclosed through a description of functional requirements.

Example:

“4.1 Business process “Providing information about educational institutions of the Russian Federation

The following participants are identified in this business process:

Moderator – an employee of the department, part of the System’s maintenance staff, responsible for the correctness of the data provided

The user is a citizen who needs to receive information about the work of educational institutions of the Russian Federation.

4.1.1 Registration of an educational institution in the System

Registration of an educational institution of the Russian Federation is carried out by the responsible employee of the institution (“Government Decree ...”).

The process of registering an educational institution includes the following steps:

• The author creates a record about the organization;
• The author enters the organization's data;
• The system checks for a license for a given organization

• If the license exists in the database, the System sends a message to the Author about successful registration;
• If the license is not found in the database, the System sends a message to the Author about the absence of a license for this organization.”

If time permits, the information provided in this section should be more fully disclosed in the appendix to the Terms of Reference document. In the appendix to the technical specifications, you can provide a screen form and below describe all the events that are present on it (creation, viewing, editing, deleting, etc.).

Requirements for the system as a whole include a disclosure of its architecture with a description of all subsystems. This part of the Terms of Reference should describe the requirements for integrating the system with other products (if any). Further, the terms of reference should include:

• requirements for system operating modes
• destination indicators
• reliability requirements
• safety requirements
• requirements for the number and qualifications of personnel and their work schedule
• information protection requirements
• requirements for the safety of information in case of accidents
• patent clearance requirements
• requirements for standardization and unification
• etc.

Requirements for types of collateral

This section of the Technical Specification document should contain requirements for mathematical, information, linguistic, software, technical and other types of support (if any).

Documentation requirements

The “Documentation Requirements” section of the technical specification includes a list of design and operational documents that must be provided to the customer.

This section of the technical specification is as important as the description of the functional requirements, so you should not limit yourself to the phrase “The Customer must be provided with all documentation in accordance with GOST 34.” This means that you must provide the entire package of documents including the “Form”, “Passport”, etc. Most of the documents from the list specified in GOST 34.201-89 are not needed by either you or the customer, so it is better to immediately agree on the list at the stage of developing the Technical Specifications document.

The minimum package of documents usually includes:

• Technical specifications;
• Statement of preliminary (technical) design;
• Explanatory note to the Technical Design;
• Description of the organization information base;
• User's Guide;
• Administrator's Guide;
• Test program and methodology;
• Acceptance test report;
• Certificate of completed work

It is better to present the list of documents in the technical specifications in the form of a table, which indicates the name of the document and the standard on the basis of which it should be developed.

Stages and stages of development

This section of the Terms of Reference document should provide information about all stages of work that must be carried out.

The description of the stage should include the name, timing, description of work and the final result.

Procedure for control and acceptance of the system

In this section of the Technical Specifications document, it is necessary to indicate the document on the basis of which acceptance tests should be carried out.

If necessary, the technical specification can be supplemented with other sections, or reduced by removing inappropriate items.

When changing the structure of the technical specifications, in order to avoid conflict situations, it must be agreed upon with the customer before developing the document.

This text was created purely for the sake of the existence of a permanent link, which the author himself, and all of you, could safely send to your future customers, colleagues, relatives and acquaintances in the form of a standardized answer to the question: “Do I need your technical specifications and what in general?” This?"

As they say - “instead of a thousand words”, since each time evangelizing for 4-5 hours on Skype on this topic is already becoming tiresome, and the global tendency to slip outright nonsense into the definition of “Technical Specifications” is only intensifying over the years.

Problem

The fact is that when there is a specific format, as well as a clear and intelligible definition of a term, then all the manipulations and substitutions of it with your own briefs, prototypes, questionnaires invented on the fly, descriptions and simply incoming applications look at least unprofessional. Therefore, we begin with the scientific definition of our concept:

Terms of reference - the original document for the design of a technical object (product). The technical specification establishes the main purpose of the object under development, its technical characteristics, quality indicators and technical and economic requirements, instructions for completing the necessary stages of creating documentation (design, technological, software, etc.) and its composition, as well as special requirements. A technical specification is a legal document - an application is included in the contract between the customer and the contractor for design work and is its basis: it determines the procedure and conditions of work, including the purpose, objectives, principles, expected results and deadlines. That is, there must be objective criteria by which one can determine whether a particular item of work has been completed or not. All changes, additions and clarifications of the wording of the technical specifications must be agreed with the customer and approved by him. This is also necessary because if inaccuracies or errors in the initial data are discovered in the process of solving a design problem, it becomes necessary to determine the degree of guilt of each of the parties involved in the development and the distribution of losses incurred in connection with this. Terms of reference, as a term in the field of information technology, is a legally significant document containing comprehensive information necessary for setting tasks for performers for the development, implementation or integration of a software product, information system, website, portal or other IT service.

Translation into understandable language

1) Technical Assignment - it sets the task. This means it should come before the prototype, sketch, test, design project, because any mindmap, data flow diagram, architecture is already the completion of a certain task, this is the answer to the question. And before the question itself has not yet been asked, formulated and signed by all parties, any answer will be a priori incorrect, right? So, the beginning of any work on any project is the formulation of a problem, and not a frantic search for sketches of a dozen options for solving it.

2) Actually, a new one logically follows from the first point - the text of the TK itself must begin with the chapter “Goals and Objectives,” which clearly formulates what business goals are being pursued by this latest attempt to increase entropy in the world. An aimless task that does not solve any problems, achieves nothing and is done “out of boredom” is not officially considered a Technical Task, and from now on is in the status of “an ordinary piece of paper”.

3) How do you understand whether the proposed design concept or an interactive prototype, or even a ready-to-use website, solves the above business problem? There’s nothing to be done, we’ll have to go back to the definition again: “determines... expected results and deadlines. That is, there must be objective criteria by which one can determine whether this or that item of work has been completed or not.” That is, technical specifications cannot exist without clear measurable indicators in rubles, seconds, ton-kilometers or degrees Celsius. Maybe a brief, or a prototype, or any other absurd piece of paper, but not the Technical Assignment.

From here we conclude that in this TOR there must be a chapter “Acceptance and Evaluation Procedure”, when these same indicators are taken, measured, and the parties either shake hands or send the project for rework.

4) The Technical Assignment must be consistent with the customer’s overall business plan, its business development strategy and market segment analysis. All this will allow you to set the right goals, derive accurate metrics, which will then be used to adequately accept the finished information product. The absence of a business plan from the customer automatically guarantees unprofessional implementation of the Technical Specifications.

Does an outsourced studio know the business goals and measurable indicators of the business better than its owner? Obviously, no, which means the correct technical specifications should be written by representatives of the Customer, and not by hired employees of the Contractor. It’s absurd when a performer sets a task for himself, then comes up with ways to evaluate it, and in the end gives himself a final mark for the work done. Ideally, such “amateur activity” should not exist, although in practice this is exactly what happens everywhere, as a result of which the Technical Assignment does not provide the necessary assistance to the project, too often being essentially a fictitious document. Don't do that.

5) Each amendment to the finished technical specification must cost money. You cannot edit the “Constitution of your project” for free and endlessly just because one of the parties changed its mind, didn’t get enough sleep, suddenly decided to save money, etc. The price of each change in the technical specifications should also be clearly stated in advance in the relevant chapter.

By the way, in theory, in the same way, every edit in the design or changes to the list of pages or functions should have a clear price, which is paid in advance, before the start of making this change. Personally, I propose that any editing of the approved technical specification should be estimated at 30% of the entire project budget, but you can do otherwise.

Is it worth mentioning that the terms of reference simply need to indicate in advance the timing and total budget for development, as well as a list of all existing resources and restrictions? - No, it will be too obvious.

So: What are we doing? For what? How will we understand what we have done? How much does each pivot cost? - the answers to all these questions written on a piece of paper are the “silver bullet” that can pull out even the most failed project.

Security questions

1) So, maybe there is also an official GOST for writing Technical Specifications? - Yes, even several.

2) What, the Technical Specification does not include a description required pages, number of buttons, libraries used, guidelines, etc.? - Not in the TOR itself, but you can put all this in the Appendices, of course adjusting all this with the above-described goals, limitations and methods for further assessing the achieved result. Post at least all future content, even a description of typical characters - but not instead of a clear statement of the task, but after it.

3) So maybe I don’t need it like that? - Perhaps today thousands of sites are made without technical specifications at all, just as thousands of people in the world live well, being blind from birth. But if you want to see where you are heading, consciously make decisions and independently evaluate the results obtained, then you cannot do without technical specifications.

4) So you and Wikipedia write that the technical specification is created by the customer. But I don’t know how/I don’t have time/I just don’t want to do it myself. How can this be? - Outsource the development of technical specifications to a third party who is completely familiar with your business, its tasks, target audience and needs, and at the same time thoroughly knowledgeable about all stages of web development. This third party will become a kind of “web notary”, that is, a guarantor that the contractor will not underestimate the indicators you need or will not delay the deadlines, and that the customer will set achievable metrics and at the final acceptance will not subjectively evaluate the created product, changing the previously recorded ones on the fly requirements.

5) And what if the technical specification is a legal document, then I can sue the outsourcer, not pay him, force him to redo everything for the tenth time? - If the document is drawn up correctly, the goals and methodology for assessing their achievement are indicated; if the document is signed by the parties and mentioned in the Agreement (the Terms of Reference itself is not an agreement) - then of course you can. But with the usual brief, prototypes, art-creative layout, Safe deal on FL - no longer.

6) They tell me that the work will be carried out using some kind of Scrum or Agile; which means I no longer need the archaic technical specification. Is that so? - Judge for yourself: they call you an incomprehensible word that clearly masks something, and now, on the basis of an unfamiliar term, they offer to abandon a legally competent document filled with goals and metrics. Agile itself cannot set any goals like “to achieve at least 10,000 visits by the end of the year”, or “to achieve more than 25 orders from the site in a month”, it’s just a way of holding meetings and new organization careless employees. Think several times: “Are they not throwing dust in your eyes?” In fact, professional technical specifications cannot harm any newfangled Scrum, but it is sure to help.

I am often asked: “How to correctly develop technical specifications for an automated system?” A similar topic is constantly discussed on various forums. This question is so broad that it is impossible to answer in a nutshell. Therefore, I decided to write a long article on this topic.

• In the first part " Development of technical specifications. What is it, why is it needed, where to start and what it should look like? I will try to answer the questions of the topic in detail, consider the structure and purpose of the Terms of Reference, and give some recommendations on the formulation of requirements.
• Second part " Development of technical specifications. How to formulate requirements? will be entirely devoted to identifying and formulating requirements for an information system.

First, you need to figure out what question actually interests those who ask “How to develop a technical specification?” The fact is that the approach to developing the technical specifications will greatly depend on the purposes for which it is being done, as well as by whom it will be used. What options am I talking about:

• A commercial organization decided to implement an automated system. It does not have its own IT service and decided to do this: The interested party must develop a Technical Specification and submit it for development to a third party;
• A commercial organization decided to implement an automated system. It has its own IT service. We decided to do this: develop a Technical Specification, then agree on it between the IT service and interested parties, and implement it on our own;
• The government agency decided to start an IT project. Everything here is so murky, a lot of formalities, kickbacks, cuts, etc. I will not consider this option in this article.

• An IT company provides services for the development and/or implementation of automated systems. This is the most difficult case, because you have to work in a variety of conditions:

  • The client has his own specialists with their own views, and they make specific requirements for the Technical Specifications;
  • The terms of reference are developed for in-house developers (the client doesn’t care);
  • The terms of reference are developed for transfer to the contractor (i.e. a group of programmers on staff of the company, or an individual specialist);
  • A misunderstanding arises between the company and the client regarding the result obtained, and the company again and again asks the question: “How should the Technical Specifications be developed?” The last case may seem like a paradox, but it is true.
  • Other, less common options are also possible;

I think the reader should now have questions:

• Why can’t the Technical Specifications always be developed in the same way?;
• Are there any standards, methods, recommendations? Where can I get them?
• Who should develop the Terms of Reference? Should this person have any special knowledge?
• How to understand whether the Terms of Reference are well written or not?
• At whose expense should it be developed, and is it even necessary?

This list can be endless. I say this with confidence because I have been in professional software development for 15 years, and the question of Technical Specifications comes up in any development team with whom I work. The reasons for this are different. Raising the topic of developing the Terms of Reference, I am well aware that I will not be able to present it 100% to everyone interested in the topic. But, I’ll try, as they say, “to sort everything out.” Those who are already familiar with my articles know that I do not use “copy-paste” of other people’s work, do not reprint other people’s books, do not quote multi-page standards and other documents that you yourself can find on the Internet, passing them off as your own genius thoughts. Just type in a search engine “How to develop a Technical Specification” and you can read a lot of interesting, but, unfortunately, repetitive things. As a rule, those who like to be clever on forums (just try searching!) have never made a proper Technical Specification themselves, and constantly quote GOST recommendations on this issue. And those who are really serious about the issue usually have no time to sit on the forums. By the way, we will also talk about GOST standards. Over the years of my work, I have seen many versions of technical documentation compiled by both individual specialists and eminent teams and consulting companies. Sometimes I also engage in this activity: I allocate time for myself and search for information on a topic of interest from unusual sources (such as a little intelligence). As a result, I had to see documentation on such monsters as GazProm, Russian Railways and many other interesting companies. Of course, I comply with the confidentiality policy, despite the fact that these documents come to me from publicly available sources or the irresponsibility of consultants (scattering information on the Internet). Therefore, I say right away: I do not share confidential information that belongs to other companies, regardless of the sources (professional ethics).

What is a technical specification?

The first thing we will do now is figure out what kind of beast this “Technical Specification” is.

Yes, there really are GOSTs and standards that attempt to regulate this part of the activity (software development). Once upon a time, all these GOSTs were relevant and actively used. Now there are different opinions about the relevance of these documents. Some argue that GOSTs were developed by very far-sighted people and are still relevant. Others say they are hopelessly outdated. Perhaps someone now thought that the truth was somewhere in the middle. I would answer in the words of Goethe: “They say that between two opposing opinions lies the truth. No way! There is a problem between them." So, there is no truth between these opinions. Because GOSTs do not reveal the practical problems of modern development, and those who criticize them do not offer alternatives (specific and systemic).

Note that GOST clearly does not even give a definition, it only says: “TK for a nuclear power plant is the main document defining the requirements and procedure for creating (development or modernization - then creation) of an automated system, in accordance with which the development of a nuclear power plant is carried out and its acceptance upon commissioning into action."

If anyone is interested in what GOSTs I’m talking about, here they are:

• GOST 2.114-95 Unified system of design documentation. Technical specifications;
• GOST 19.201-78 Unified system of program documentation. Technical specifications. Requirements for content and design;
• GOST 34.602-89 Information technology. A set of standards for automated systems. Terms of reference for the creation of an automated system.

A much more successful definition is presented on Wikipedia (though about technical specifications in general, and not just for software): “ Technical specifications– this is the original design document technical object. Technical specifications establishes the main purpose of the object under development, its technical and tactical-technical characteristics, quality indicators and technical and economic requirements, instructions for completing the necessary stages of creating documentation (design, technological, software, etc.) and its composition, as well as special requirements. A task as an initial document for the creation of something new exists in all areas of activity, differing in name, content, order of execution, etc. (for example, a design task in construction, a combat task, homework, a contract for a literary work, etc.). d.)"

And so, as follows from the definition, the main purpose of the Technical Specification is to formulate the requirements for the object being developed, in our case, for an automated system.

It is the main thing, but the only one. The time has come to get down to the main thing: to put everything “on the shelves”, as promised.

What do you need to know about the requirements? It is necessary to clearly understand that all requirements must be divided by type and properties. Now we will learn how to do this. To separate requirements by type, GOST will help us. The list of types of requirements that is presented there is a good example of what types of requirements should be considered. For example:

• Functionality requirements;
• Security and access rights requirements;
• Requirements for personnel qualifications;
• …. Etc. You can read about them in the mentioned GOST (and below I will also consider them in a little more detail).

I think it is obvious to you that the key factor in a successful Technical Specification is precisely well-formulated functionality requirements. Most of the works and techniques that I spoke about are devoted to these requirements. Functionality requirements are 90% of the complexity of the work on developing the Terms of Reference. Everything else is often a “camouflage” that covers these requirements. If the requirements are formulated poorly, then no matter what beautiful camouflage you put on them, a successful project will not come out. Yes, formally all requirements will be met (according to GOST J), the technical specification has been developed, approved and signed, and money has been received for it. And what? And then the most interesting part begins: what to do? If this is a project on the State Order, then there are no problems - the budget there is such that it won’t fit into anyone’s pocket, and during the implementation process (if there is one) everything will be clarified. This is exactly how the majority of project budgets are spent on State Orders (they scribbled “TZ”, lost tens of millions, but did not do the project. All formalities were observed, there were no culprits, a new car is near the house. Beauty!). But we are talking about commercial organizations where money is counted, and a different result is needed. Therefore, let's understand the main thing, how to develop useful and working Technical specifications.

I said about the types of requirements, but what about properties? If the types of requirements can be different (depending on the goals of the project), then with properties everything is simpler, there are 3 of them:

1. The requirement must be understandable;
2. The requirement must be specific;
3. The requirement must be test takers;

Moreover, the last property is impossible without the two previous ones, i.e. is a kind of “litmus test”. If the result of a requirement cannot be tested, it means that it is either unclear or not specific. Think about it. It is in the mastery of these three properties of requirements that mastery and professionalism lie. It's actually very simple. When you figure it out.

This concludes the story about what a Technical Specification is and moves on to the main thing: how to formulate requirements. But it's not that fast. There is one more extremely important point:

• In what language (in terms of difficulty of understanding) should the technical specification be written?
• Should it describe the specifications of various functions, algorithms, data types and other technical things?
• What is technical design, which, by the way, is also mentioned in GOSTs, and how is it related to the Technical Specifications?

There is a very insidious thing hidden in the answers to these questions. That is why disputes often arise about the sufficiency or lack of necessary detail of requirements, about the understandability of the document by the Customer and Contractors, about redundancy, presentation format, etc. Where is the line between the Terms of Reference and the Technical Project?

Technical specifications– this is a document based on requirements formulated in a language that is understandable (ordinary, familiar) to the Customer. In this case, industry terminology that is understandable to the Customer can and should be used. There should be no connections to the specifics of the technical implementation. Those. at the technical specification stage, in principle, it does not matter on which platform these requirements will be implemented. Although there are exceptions. If we are talking about implementing a system based on an already existing software product, then such a connection can take place, but only at the level of screen forms, report forms, etc. The clarification and formulation of requirements, as well as the development of Terms of Reference should be carried out business analyst. And certainly not a programmer (unless he combines these roles, this happens). Those. this person must speak to the Customer in the language of his business.

Technical project– this is a document that is intended for the technical implementation of the requirements formulated in the Terms of Reference. This document describes data structures, triggers and stored procedures, algorithms and other things that will be required technical specialists. The customer does not have to delve into this at all (even such terms may not be clear to him). Technical project does System Architect(combining this role with a programmer is quite normal). Or rather, a group of JSC specialists led by an architect. The larger the project, the more people work on the Terms of Reference.

What do we have in practice? It’s funny to watch when the director is presented with a technical specification for approval, which is replete with technical terminology, descriptions of data types and their values, database structure, etc. He, of course, tries to understand, since he needs to approve, trying to find familiar words between the lines and not lose the chain business requirements. Is this a familiar situation? And how does it end? As a rule, such technical specifications are approved, then implemented, and in 80% of cases, then they do not at all correspond to the fact of the work performed, because they decided to change, redo a lot of things, misunderstood, thought wrong, etc. etc. And then the series about submitting work begins. “But here it’s not what we need,” but “this won’t work for us,” “it’s too complicated,” “it’s inconvenient,” etc. Sound familiar?!! That’s familiar to me, I had to hit the bumps in due time.

So what do we have in practice? But in practice, we have a blurred boundary between the Terms of Reference and the Technical Project. She floats between TK and TP in a variety of manifestations. And that's bad. This happens because the development culture has become weak. This is partly due to the competencies of specialists, partly due to the desire to reduce budgets and deadlines (after all, documentation takes a lot of time - that’s a fact). There is another important factor influencing the use of the Technical Design as a separate document: the rapid development of rapid development tools, as well as development methodologies. But this is a separate story; I’ll say a few words about it below.

Another small but important point. Sometimes Terms of Reference are called a small piece of requirements, simple and understandable. For example, improve the search for an object based on some conditions, add a column to the report, etc. This approach is quite justified, why complicate life. But it is used not on large projects, but on minor improvements. I would say this is closer to software product maintenance. In this case, the Terms of Reference may also describe a specific technical solution for implementing the requirement. For example, “Make such and such a change to such and such an algorithm,” indicating a specific procedure and a specific change for the programmer. This is the case when the boundary between the Terms of Reference and Technical Projects is completely erased, because there is no economic feasibility to inflate paperwork where it is not needed, but a useful document is created. And that's right.

Is technical specification necessary at all? What about the Technical Project?

Am I overheating? Is this possible without any Technical specifications? Imagine it is possible (or rather, it is possible), and this approach has many followers, and their number is growing. As a rule, after young specialists have read books about Scrum, Agile and other rapid development technologies. In fact, these are wonderful technologies, and they work, but they don’t literally say “no need to do technical tasks.” They say “a minimum of paperwork,” especially unnecessary ones, closer to the Customer, more specifics and faster results. But no one canceled the recording of requirements, and this is clearly stated there. It is there that the requirements are fixed based on the three remarkable properties that I spoke about above. It’s just that some people’s minds are structured in such a way that if something can be simplified, then let’s simplify it to the point of complete absence. As Einstein said " Make it as simple as possible, but not simpler than that." . These are golden words that go with everything. So Technical specifications necessary, otherwise you won’t see a successful project. Another question is how to compose and what to include there. In the light of rapid development methodologies, you need to focus only on the requirements, and all the “camouflage” can be discarded. In principle, I agree with this.

What about the Technical Project? This document is very useful and has not lost its relevance. Moreover, often you simply cannot do without it. Especially when it comes to outsourcing development work, i.e. on the principle of outsourcing. If you don't do this, you run the risk of learning a lot about what the system you have in mind should look like. Should the Customer become familiar with it? If he wants, why not, but there is no need to insist and approve this document, it will only hold back and interfere with work. It is almost impossible to design a system down to the smallest detail. In this case, you will have to continuously make changes to the Technical Design, which takes a lot of time. And if the organization is heavily bureaucratic, then you will leave all your nerves there. Reducing this kind of design is exactly what modern rapid development methodologies that I mentioned above are all about. By the way, they are all based on the classic XP (extreme programming) - an approach that is already about 20 years old. So make a high-quality Technical Specification that is understandable to the Customer, and use the Technical Design as an internal document for the relationship between the system architect and programmers.

An interesting detail about technical design: some development tools designed on the principle of subject-oriented design (such as 1C and similar) assume that design (meaning the documentation process) is required only in truly complex areas where interaction between entire subsystems is required. In the simplest case, for example, creating a directory or document, only correctly formulated business requirements are enough. This is also evidenced by the business strategy of this platform in terms of training specialists. If you look at the exam card of a specialist (that’s what it’s called, not a “programmer”), you will see that there are only business requirements, and how to implement them in a program language is the specialist’s task. Those. that part of the problem that the Technical Project is intended to solve, the specialist must solve “in his head” (we are talking about tasks of medium complexity), here and now, following certain development and design standards, which again are formed by the 1C company for its platform. Thus, of two specialists whose work results look identical, one can pass the exam, but the other cannot, because flagrantly violated development standards. That is, it is obviously assumed that specialists must have such qualifications that they can design typical tasks independently, without the involvement of system architects. And this approach works.

Let’s continue to study the question: “What requirements should be included in the Terms of Reference?”

Formulation of requirements for the information system. Structure of the Terms of Reference

Let’s be clear right away: we will talk specifically about formulating requirements for an information system, i.e. assuming that the work on developing business requirements, formalizing business processes and all previous consulting work has already been completed. Of course, some clarifications can be made at this stage, but just clarifications. The automation project itself does not solve business problems - remember this. This is an axiom. For some reason, some managers are trying to refute it, believing that if they buy the program, order will come to a chaotic business. But an axiom is an axiom because it does not require proof.

Like any activity, formulating requirements can (and should) be divided into stages. Everything has its time. This is hard intellectual work. And, if you treat it with insufficient attention, then the result will be appropriate. According to expert estimates, the cost of developing the Terms of Reference can be 30-50%. I am of the same opinion. Although 50 is perhaps too much. After all, the Technical Specification is not the last document that must be developed. After all, there must also be technical design. This variation is due to different automation platforms, approaches and technologies used by project teams during development. For example, if we are talking about development in a classical language like C++, then detailed technical design is indispensable. If we are talking about implementing a system on the 1C platform, then the situation with design is somewhat different, as we saw above (although, when developing a system from scratch, it is designed according to the classical scheme).

Although the requirements statement is the main part Technical specifications, and in some cases it becomes the only section of the technical specifications, you should pay attention to the fact that this is an important document, and it should be drawn up accordingly. Where to start? First of all, you need to start with the content. Write the content and then start expanding it. Personally, I do this: first I sketch out the content, describe the goals, all the introductory information, and then get down to the main part - the formulation of requirements. Why not the other way around? I don't know, it's more convenient for me. Firstly, this is a much smaller part of the time (compared to the requirements), and secondly, while you are describing all the introductory information, you tune in to the main thing. Well, whoever likes it. Over time, you will develop your own Technical Specification template. To begin with, I recommend taking as content exactly the one described in GOST. It's perfect for content! Then we take and begin to describe each section, not forgetting about the recommendations of following three properties: understandability, specificity and testability. Why do I insist on this so much? More on this in the next section. And now I propose to go through those points of the technical specifications that are recommended in GOST.

1. general information;
2. purpose and goals of creation (development) of the system;
3. characteristics of automation objects;
4. system requirements;
5. composition and content of work to create the system;
6. procedure for control and acceptance of the system;
7. requirements for the composition and content of work to prepare the automation object for putting the system into operation;
8. documentation requirements;
9. development sources.

In total, 9 sections, each of which is also divided into subsections. Let's look at them in order. For convenience, I will present everything in the form of a table for each item.

Section 1. general information.

Section 2. purpose and goals of creation (development) of the system.

In general, the ability to identify goals, formulate them, and build a tree of goals is a completely separate topic. Remember the main thing: if you know how, write, if you are not sure, don’t write at all. What happens if you don’t formulate goals? You will work according to the requirements, this is often practiced.

Section 3. Characteristics of automation objects.

Section 4. System Requirements

GOST deciphers the list of such requirements:

• requirements for the structure and functioning of the system;
• requirements for the number and qualifications of system personnel and their mode of operation;
• destination indicators;
• reliability requirements;
• safety requirements;
• requirements for ergonomics and technical aesthetics;
• transportability requirements for mobile speakers;
• requirements for operation, maintenance, repair and storage of system components;
• requirements for protecting information from unauthorized access;
• requirements for the safety of information in case of accidents;
• requirements for protection from external influences;
• requirements for patent purity;
• requirements for standardization and unification;

Despite the fact that the main one will certainly be the section with specific requirements (functional), this section can also be of great importance (and in most cases it is). What may be important and useful:

• Qualification Requirements. It is possible that the system being developed will require retraining of specialists. These can be both users of the future system and IT specialists who will be needed to support it. Insufficient attention to this issue often develops into problems. If the qualifications of the existing personnel are clearly insufficient, it is better to specify requirements for the organization of training, training program, timing, etc.
• Requirements for protecting information from unauthorized access. No comments here. These are precisely the requirements for delimiting access to data. If such requirements are planned, then they need to be written separately, in as much detail as possible, according to the same rules as functional requirements (understandability, specificity, testability). Therefore, these requirements can be included in the section with functional requirements
• Requirements for standardization. If there are any design standards that are applicable to the project, they can be included in the requirements. As a rule, such requirements are initiated by the Customer’s IT service. For example, the 1C company has requirements for the design of program code, interface design, etc.;
• Requirements for the structure and functioning of the system. Here the requirements for integrating systems with each other can be described, and a description of the general architecture is presented. More often, integration requirements are generally separated into a separate section or even a separate Technical Specification, because these requirements can be quite complex.

All other requirements are less important and need not be described. In my opinion, they only make the documentation heavier and have little practical benefit. And it is very difficult to describe ergonomic requirements in the form of general requirements; it is better to transfer them to functional ones. For example, the requirement “Get information about the price of a product by pressing only one button” may be formulated. In my opinion, this is still closer to specific functional requirements, although it relates to ergonomics. Requirements for functions (tasks) performed by the system This is the main and key point that will determine success. Even if everything else is done perfectly, and this section is “3”, then the result of the project will be at best “3”, or even the project will fail altogether. This is what we will deal with in more detail in the second article, which will be included in the 5th issue of the newsletter. It is to this point that the “rule of three properties of requirements” that I spoke about applies. Requirements for types of collateral

GOST identifies the following types:

• Mathematical
• Informational
• Linguistic
• Software
• Technical
• Metrological
• Organizational
• Methodical
• and others...

At first glance, these requirements may seem unimportant. In most projects this is true. But not always. When to describe these requirements:

• No decisions have been made on which language (or platform) development will be carried out;
• The system requires a multilingual interface (for example, Russian/English)
• For the system to function, a separate unit must be created or new employees must be hired;
• For the system to function, the Customer must undergo changes in work methods and these changes must be specified and planned;
• Integration with any equipment is expected and requirements are imposed on it (for example, certification, compatibility, etc.)
• Other situations are possible, it all depends on the specific goals of the project.

Section 5. Composition and content of work to create the system

Section 6. Procedure for control and acceptance of the system

General requirements for acceptance of work by stages (list of participating enterprises and organizations, place and timing), procedure for coordination and approval of acceptance documentation; I strongly recommend that you take responsibility for the procedure for submitting work and checking the system. This is exactly why testable requirements are needed. But even the presence of testable requirements may not be enough when the system is delivered if the procedure for acceptance and transfer of work is not clearly stated. For example, a common trap: the system is built and is fully operational, but the Customer for some reason is not ready to work in it. These reasons can be any: no time, goals have changed, someone quit, etc. And he says: “Since we are not yet working in the new system, it means we cannot be sure that it works.” So learn to correctly identify stages of work, and ways to check the results of these stages. Moreover, such methods must be clear to the Customer from the very beginning. If they are fixed at the level of the Technical Specifications, then you can always turn to them if necessary and complete the work with the transfer.

Section 7. Requirements for the composition and content of work to prepare the automation object for putting the system into operation

There may be any other rules for entering information adopted by the company (or planned). For example, information about a contract used to be entered as a text string in any form, but now a separate number, a separate date, etc. are required. There can be a lot of such conditions. Some of them may be perceived with resistance from staff, so it is better to register all such cases at the level of requirements for the order of data entry. Changes that need to be made in the automation object

Creation of conditions for the functioning of the automation object, under which the compliance of the created system with the requirements contained in the technical specifications is guaranteed. Any changes that may be required. For example, the company does not have a local network and has an outdated fleet of computers on which the system will not work.

Perhaps some necessary information was processed on paper, and now it needs to be entered into the system. If you do not do this, then some module will not work, etc.

Perhaps something was simplified, but now needs to be taken into account in more detail, so someone must collect information according to certain rules.

This list can be long, look at the specific case of your project. Creation of departments and services necessary for the functioning of the system;

Timing and procedure for staffing and training We have already talked about this earlier. Perhaps the system is being developed for a new structure or type of activity that did not exist before. If there are no appropriate personnel, and even trained ones, the system will not work, no matter how competently it is built.

Section 8. Documentation Requirements

Consider how user manuals will be presented.

Perhaps the Customer has accepted corporate standards, which means we need to refer to them.

Ignoring documentation requirements very often leads to the most unexpected consequences on projects. For example, everything is done and everything works. Users also know how to work. There was no agreement or conversation about documentation at all. And suddenly, when handing over the work, one of the Customer’s top managers, who did not even participate in the project, but is involved in accepting the work, asks you: “Where are the user manuals?” And it begins to convince you that there was no need to agree on the availability of user manuals, this is supposedly implied “of course.” And that’s it, he doesn’t want to take your job. At whose expense will you develop the guidelines? Many teams have already fallen for this hook.

Section 9. Development Sources

Therefore, it is better to simply refer to the survey report and the requirements of key persons.

And so, we have considered all the sections that can be included in the Terms of Reference. “Can” and not “Must” precisely because any document must be developed to achieve a result. Therefore, if it is obvious to you that a particular section will not bring you any closer to the result, then you don’t need it and you don’t need to waste time on it.

But no competent technical specification can do without the main thing: functional requirements. I would like to note that in practice such Technical Specifications occur, and how! There are people who will be able to separate the waters in all sections, describe the general requirements in general terms, and the document turns out to be very weighty, and there are a lot of clever words in it, and even the Customer may like it (that is, he will approve it). But it may not work according to it, i.e. It has little practical use. In most cases, such documents are born when you need to get a lot of money specifically for the Terms of Reference, but it needs to be done quickly and without diving into details. And especially if it is known that the matter will not go further, or completely different people will do it. In general, just to manage the budget, especially the state budget.

In the second article we will talk only about section 4 “System requirements”, and specifically we will formulate requirements for reasons of clarity, specificity and testability.

Why requirements must be clear, specific and testable.

Because practice shows: at first, most of the technical requirements that are developed by specialists either turn out to be not in demand (do not correspond to reality), or become a problem for those who must implement them, because The customer begins to manipulate non-specific terms and requirements. I will give several examples of what phrases were encountered, what this led to, and then I will try to give recommendations on how to avoid such problems.

Is this requirement testable? It seems simple thing, but how to check it if there are no specifics?

How this could be reformulated: “The amount of costs specified in the document must be distributed to all goods specified in this document in proportion to the cost of these goods.” It turned out both clear and specific. How to check is also not difficult.

Ergonomics The program must have a user-friendly interface. I must admit, I once had to subscribe to this formulation myself - there were countless problems later. Of course, such formulations should not exist. There are no specifics here, nor the opportunity to verify this requirement. Although, of course, it is understandable (subjective). There is no way to reformulate this; each element of “convenience” must be described in detail, since the Customer insists on it. For example:

• Lines should be added to the document both by clicking on the “Add” button and by pressing the “insert” key, as well as by the user entering part of the name;
• When viewing a list of products, it should be possible to search by name, barcode and article;
• Etc.

Differentiation of access rightsAccess to profit data should only be available to the financial director. Is that clear? Almost. True, profits vary, we need to clarify. Specifically? Of course not. How does this look like in implementation? If we are talking about gross profit, then it is necessary to limit access to data on the cost of purchases, because otherwise, gross profit will not be difficult to calculate, since data on the cost of sales is known to a wide range of people. What concerns access rights must be treated very carefully. And if sales managers’ motivation is based on gross profit, then these requirements also contradict each other, because managers will never be able to verify this. If we are to include such a requirement, then we need to specify specific reports and system objects that indicate what part of the data should be available to certain categories of persons. And consider each such case individually. Productivity The sales report should be generated in 1 minute. Yes, I understand. And there is even a specific time limit: 1 minute. But it is not known what kind of detailing is expected: for each product, product groups, customers, or something else? It can be formulated something like this: “A sales report by customer with detail for each product item (see sample) should not be displayed more than 1 minute, provided that the number of products in the sample does not exceed 5000 lines.”

I hope the idea is clear. If you have specific questions, write, I will try to help.

To Terms of reference there were more specifics, there are many recommendations. There is even a list of words that are not recommended to be used in the Technical Specifications. K. Wiegers writes interestingly about this in his book “Development of Software Requirements.” I will give the most interesting and simple, in my opinion, recommendations:

• You should not use words that have many synonyms. If this is necessary, it is better to give a clear definition of the term in the “Terms and Definitions” section of the Terms of Reference.
• You should try not to use long sentences;
• If a requirement seems too general to you, it needs to be detailed into smaller but specific requirements;
• Use more schemes, graphs, tables, drawings - this way information is perceived much easier;
• Words to avoid are: “effective”, “adequate”, “simple”, “clear”, “fast”, “flexible”, “improved”, “optimal”, “transparent”, “sustainable”, “sufficient”, “ friendly”, “easy”, etc. The list can be continued, but I think the idea is clear (try to continue it yourself).

Everything written above is important information, but not the most important. As you remember, at the beginning of the article I called this the term “camouflage”, because. the most important thing that will make up at least 90% of the time and complexity of working on a document is identifying and formulating requirements. And you still need to be able to collect, structure and formulate information about requirements. This, by the way, has a lot in common between a survey of enterprise activities and a subsequent description of business processes. But there are also important differences. One of these key differences is the presence of the stage of building a prototype of the future system, or as it is also called “information system model”.

In the next article we will talk only about methods for identifying requirements, and also consider what is common between the work of collecting requirements for an information system and collecting information to describe business processes.

Types of work when collecting requirements for an accounting system and information to describe business processes. Part 2

In this part we will talk about how to organize the requirements gathering stage, what it should consist of and what tools can be used. I repeat that this work, in terms of stages, is very similar to a survey of an enterprise to describe business processes.

As usually happens in life:

Why did the practice develop as described above? Frankly, I don't know. Ask anyone, no one knows. At the same time, the situation is not changing very quickly, although people constantly discuss this topic, exchange experiences, write books... It seems to me that one of the reasons is low quality appropriate education. It may also be due to the fact that many specialists come from other businesses and learn everything in practice, i.e. their experience is formed in the environment where they find themselves. The attitude of universities and their lack of desire to be closer to reality is also a well-known fact, but sometimes I am surprised by their position. For example, I had a case when a graduate student, a talented specialist, wanted to write a thesis on the 1C platform (a good industry development), but the department told her that regardless of the topic, she could not count on an “excellent” grade, because 1C is not a serious system. The point here is not the seriousness and objectivity of this opinion, but the fact that a primitive task in a classical programming language was immediately considered worthy of an “excellent” rating.

Let's try to make the process discussed above more systematic approach. What might he look like then?

As you can see, the process ends with a question, because At this point, the work is far from finished, and then the most difficult and most practical will begin - exactly what will determine the applicability of the obtained result in real life. This is exactly what will determine the fate of the previous work: either it will go to the closet (on a shelf or somewhere else), or it will represent a valuable source of information. And even better if it becomes a model for subsequent projects.

I would like to especially note that until the last step in the diagram (where the question is) general principle collecting information about the company’s activities looks the same, regardless of what you plan to do in the future, describe business processes or implement an automated system. Yes, the sequence of steps itself is the same, but the tools used in some of them may differ. We at the moment We will definitely consider it when we study the methods and tools of individual stages. We will do this in detail in separate articles, but now we will consider only the most important things. Further steps will differ and will be determined by what is required from the project: describe business processes or implement an accounting system.

Let's look at how we can reorganize the approach to collecting information about a company's activities.

So we get to the question “What’s next?” Next we will consider the tasks of describing business processes and developing technical specifications separately. It is no coincidence that I consider these tasks in parallel. There really is a lot in common between them, which is what I want to demonstrate. First, let's look at the sequence of work when describing business processes.

Now let’s look at what the approach to studying the requirements for an information system will look like with their further reflection in the Terms of Reference

Yes, the development of Terms of Reference is a labor-intensive process, and therefore costly. But if it is done correctly, it relieves the Customer of unfulfilled expectations. The contractor has to do what the Customer requires and not redo the same thing a hundred times. And in general, it gives the whole project transparency.