Prepare technical specifications for development. Development of technical specifications

I am often asked: “How to correctly develop technical specifications for an automated system?” The topic of developing technical specifications is constantly discussed in 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 process of working on the article, I realized that it would not be possible to put everything in one article, because... It will be about 50 pages and I decided to break it into 2 parts:

• 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 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’ve been in professional development for 15 years already. software, and the question of Technical Specifications comes up in any development team with whom you 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 done 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. IN different years In my work, I had to see 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 regarding 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. In no case! 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 that defines 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 one system design documentation. Technical specifications;
• GOST 19.201-78 Unified system of program documentation. Technical task. Requirements for content and design;
• GOST 34.602-89 Information technology. 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 task- this is the original design document technical object. Technical task establishes the main purpose of the object being developed, 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 literary work etc.)"

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 good example which 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 look at 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 methods 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 don’t put on any beautiful camouflage on them, successful project will not work. 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 “TK”, 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're 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 another 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 task- 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 screen forms, report forms, etc. The clarification and formulation of requirements, as well as the development of Terms of Reference should be carried out by 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. and so on. And then the series about submitting work begins. “But here it’s not what we need,” but “this won’t work for us,” “this is too complicated,” “this is 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 TZ and TP in the most different 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 according to some conditions, add a column to the report, etc. This approach is quite justified, why complicate life. But it does not apply to 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, and a useful document is created. And it is 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 mentioned 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 task necessary, otherwise you won’t see a successful project. Another question is how to compose it 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 insist and assert this document there is no need, it will only hold you back and interfere with your 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’ll 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.

Interesting detail about technical design: some development tools designed according to the subject-oriented principle (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 just an axiom; 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. By expert assessments, 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 begin? 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 what is 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 am I so insistent on this? 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;
• operating requirements, 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, of course, will be the section with specific requirements (functional), this section may also have great importance(and in most cases it does). 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 precisely 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 new system, which means we can’t 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 commissioning of the system

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, 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 “of course” implied. 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 closer to the result, then you do not need it and you do not 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 figures who will be able to separate the waters in all sections, describe General requirements in general terms, 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 specifications that are developed by specialists either turn out to be not in demand (do not correspond to reality), or become a problem for the one who must implement them, because The customer begins to manipulate vague terms and requirements. I will give a few examples of what phrases were encountered, what this led to, and then I will try to give recommendations on how to avoid such problems.

In life, it often happens that a person cannot explain what he wants, even in everyday things. When it comes to explaining your “wants” to a programmer, a person simply falls into a stupor.

Ideally, the technical specifications should be drawn up by the customer - only he knows what he needs. But in practice, due to the customer’s low competence in the 1C field, this often has to be done by the contractor. The customer verbally voices his needs, and the programmer (consultant) puts it in writing.

Why do you need technical specifications?

Any, ideally, should be accompanied by technical specifications. This is, firstly, a clear definition of the task, deadlines and method of implementation. Secondly, this is a document with the help of which all controversial issues in the future are resolved. Whether to write technical specifications or not is, of course, your business; for me personally, technical specifications make my work and communication with the client easier.

Get 267 video lessons on 1C for free:

What should the terms of reference contain?

Those. the assignment must contain:

• target— the problem that we will solve by implementing this specification;
• description — summary upcoming improvements;
• implementation method — detailed description methods for solving the goal. At this point, it is necessary to describe all the nuances of the task in the programmer’s language: what kind of tasks we are creating/editing, what the interface should look like, etc. If you do not speak “programmer language”, but “have heard something”, it is better not to try to write in a technical language - it turns out to be quite fun. The description should be unambiguous and not raise questions. It may also contain an example of implementing a similar solution in another area;
• performance evaluation- Very important point, description of labor costs.

There are also state standards for writing technical specifications - GOST standards. In practice, they are rarely used, but sometimes the customer insists on it.

From experience, when handing in work, situations very often arise like “we told you then...”, which is not very pleasant, and often you have to redo the entire work. Therefore, a well-written technical specification makes life much easier for both parties.

Examples and samples of technical specifications for 1C

A small selection that I found freely available on the Internet. Starting from the simplest and most accessible to quite complex documents.

The question “Is it necessary to draw up a technical specification (TOR) at all?” may arise only for those who have never ordered the development of a website in their lives, since the need for it arises after the first communication between the customer and the contractor.

A technical specification is a document that describes the future project in detail and completely. The more detailed it is, the more accurately the idea will be implemented and the fewer conflicts and controversial situations will arise during the implementation of the project, because absolutely any thing can be done in different ways. It can be referenced if something is not completed or done incorrectly or other errors are made. Before starting work, the customer usually describes the future project in abstract form or fills out a brief, and the contractor formalizes all these requirements and wishes, and, if necessary, proposes adjustments. At the same time, the customer needs to make sure that all his “wants” are recorded in the specifications.

If an agreement is concluded with a web studio or freelancer to develop a website, then the technical task usually comes as an appendix to it. And in controversial situations, they are guided by what is written there.

What does the technical specification consist of?

Suppose, as part of a project, you need to draw up technical specifications for the development of a website for the Pero copywriting studio. What points should it contain?

General information (description)

Here are the following:

Company information. general information about the studio, what it does. It would be a good idea to provide a list of services provided. Here you can add the address of the future website and contact information.

Stages and timing of the project. A very important point: as a rule, a schedule for all stages of work is drawn up at the very end. This part gives an understanding of what will be done and when. For example (with dates):

• Preparatory stage;
• Development of the website concept;
• Design;
• Creation of a design layout;
• Page design development;
• Layout;
• Programming;
• Filling content;
• SEO optimization;
• Testing;
• Launch.

Some stages, for example, SEO promotion, may not exist. Depends on the goals and objectives of the customer and the competencies of the contractor.

Purpose and goals

Here it is formulated what functions the site will perform and for whom it is intended.

Purpose of the site. What goals should be achieved by creating a website? Why is it needed, what problems does it solve?

• Advertising and attracting new clients;
• Customer and partner support;
• Demonstration of completed work;
• Familiarization with the list of services;
• Creating and maintaining the company's image.

Perhaps some points should be described in more detail. For example, if the site’s task is also to inform visitors, then it is better to explain what exactly it is about.

The target audience. Who will use the site, for whom is it created?

• Webmasters, bloggers;
• Owners of online stores;
• Owners of information portals;
• Advertising studios;
• Representatives of firms and companies present in the online space.

Requirements

A large and extremely important section, which takes into account as many design and development aspects as possible, because the customer will have to pay extra for functionality not specified in the technical specifications.

Type. What category does the web resource belong to?

• Landing page;
• Business card website;
• Corporate website;
• Informational portal;
• Online store.

Registration requirements. They can be of the following type:

• The website should be minimalistic and at the same time reflect the type of activity of the company.
• Primary colors: green and white, according to the brand book or at the discretion of the designer.
• You cannot use animation, pop-ups, Flash elements, or design excesses in the design.
• Serif fonts cannot be used (standard ones can be used: Verdana, Arial, Tahoma, etc.). The font size should ensure maximum readability (12-16 pt.).

As for design requirements, different approaches can be used. If the customer himself knows exactly what he wants to receive, then he describes his wishes in detail, gives examples of sites that he likes and gives other specifics. But sometimes it happens that he himself does not know exactly how it all should look, in this case they usually proceed from the tasks that the design should solve. The contractor develops concepts, offers solutions, defends his idea and adjusts it based on the customer’s comments. The second option is more expensive and requires more qualifications from the contractor.

Language requirements. Which language speakers will be able to access the resource? What language versions of the site should there be?

• Russian;
• English;
• Esperanto.

Compatibility Requirements. From which devices and which browsers will the site open correctly? IN Lately there is a tendency towards adaptive layout, when the page displays correctly on any device with any aspect ratio and screen resolution. Here you can list the browsers with which the resource should definitely be compatible. Usually for everyone modern browsers sites are displayed the same, there are only problems with older versions of Internet explorer.

CMS requirements. Site administration capabilities determine which blocks can be edited and configured through the control panel, without interfering with the code or directly editing the database, but using a convenient visual interface. For example, it can be formulated like this:

• Ability to change content on site pages;
• Ability to manage pages (adding, renaming, deleting, etc.);
• Ability to edit the site structure and menu items;
• Automatic graphics processing functions (creating previews, transformation to a given size, etc.);
• Ability to write unique Meta tags;

As in other subsections, you need to describe all requirements and wishes.

Often the customer already has experience working with one of the popular CMS, then it is advisable to look for contractors for a specific engine. Also, when choosing a CMS, it is better not to settle for self-written solutions, because in the future this will depend on the performer. Self-written engines, in my opinion, are justified only in very large projects where specific functionality or optimization of large loads is required.

Structure and navigation. What sections, subsections and individual pages will the project contain?

• Home page
• Services

• Copywriting
• Rewriting
• SEO copywriting
• Proofreading
• Transcription
• Content management
• Content Marketing

• Portfolio
• About Us
• Contacts

Do and short description each page, give definitions. For example, what is meant by a “Contact” page? It must contain address, telephone and email in text form? Or should there be a feedback form there? Or maybe you need to embed the Yandex Maps code? Or should all of the above be placed on the contacts page, plus links to representatives on social networks?

It is advisable to prepare the content or at least outline it before starting work with the contractor. This will promote more effective communication.

Additional requirements. Everything that is not included in other sections of the section.

Description of website sections

At this point there are details. Usually the content of all unique pages is described: what elements will be there, how the user will interact with them.

Home page. The problem formulation can be as follows.

The main part of the main page should be made in the form of Landing Page. The following elements should be located on it from top to bottom:

• Header - logo, company name;
• Navigation menu;
• Information about promotions and discounts;
• Order button;
• Advertising text;
• Block with five best works and a link to the portfolio section;

How to purchase what you need without violating antitrust laws? The key to success in this matter is a well-written technical specification. Read in the article what implicit violations are committed by customers.

IN general case When drawing up a procurement specification, the customer must ensure that the object being described is completely impersonal, that is, it should not contain any requirements or even hints at specific trademarks, manufacturers, or even the country of origin of the product.

In fact, it is quite difficult to competently prepare a description of the procurement object, technical specifications under 44-FZ, without special knowledge in a specific area. Some customers even create purchases for the provision of services for the preparation of technical specifications. But it’s quite possible to do this yourself if you carefully study the requirements for procurement objects, compare them with your needs and strictly follow the rules for describing the procurement object according to 44-FZ.

It must be borne in mind that some characteristics are encrypted in the product labeling. For example, the technical specifications provide for the material “paving slabs” marked “Classico 1KO.4”; the technical specifications do not make any requirements for the thickness of the tiles. According to the decoding of the marking, its thickness is 4 cm (the last digit of the marking indicates the thickness in centimeters). However, when making the contact, it turned out that a 6 cm thick tile was required. The thickness of the tile determines the load that it can withstand. An illiterate technical specification led to the purchase of material that did not meet the necessary requirements. Therefore, you need to carefully check the labeling of all materials in the technical specifications and indicate all the basic, important requirements for the materials.

Preferably do not copy product descriptions from different sites. The information in the description may not be reliable and it may turn out that not a single product meets the stated requirements. There is a high probability that under this description The only product that fits. This may be regarded as a restriction of competition.

All performance requirements must be unambiguous. Otherwise there will be a lot of requests for clarification. It often happens that with many requests, the customer cannot keep up with deadlines There may not be enough time to answer them on the merits and there may not be time to adjust the technical specifications. Based on this, sometimes the customer indicates in an explanation that it is enough to submit only consent, without indicating the materials. In turn, this reduces the chances of purchasing exactly what is needed, since it is not clear from the application what materials will be used in the execution of the work.


It is better to draw up instructions for preparing an application after describing the requirements for technical specifications. The instructions should not confuse the participant, but specify the requirements of the technical specifications, in order to avoid many requests from participants. Inconsistency of the technical specifications with the instructions, which creates an obstacle to the preparation of the application, may provoke the filing of complaints by potential procurement participants with the Federal Antimonopoly Service.

What other requirements are important to indicate in the terms of reference:

• To the warranty period of a product, work, service and (or) the scope of providing guarantees of their quality. The customer must establish a warranty period in the technical specifications that is no less than the manufacturer’s warranty period.
• For product warranty service.
• To the costs of operating the product.
• To the obligatory implementation of installation and adjustment of the product.
• To train persons involved in the use and maintenance of the product.

Main rules

1. When preparing procurement documentation, pay attention to the All-Russian Product Classification (OKPD2) codes related to the procurement object. It is necessary that the code used matches the specific procurement object.
2. In addition to the provisions of 44-FZ, when developing technical specifications, one should also keep in mind the requirements of other legal acts, antimonopoly authorities, technical standards and standards (GOST, TU, SNiP, etc.).
3. The goods and materials requested by the customer in the technical specifications must correspond to the object of purchase and estimate documentation(if there is one).
4. When purchasing for a construction contract, you must also attach defective statement, estimate, and in case capital construction(reconstruction, overhaul) design documentation must also be attached.
5. Indicate that you want to purchase new goods and materials (i.e. they have not been used, have not been repaired, restored, or restored). Otherwise, the customer may receive used goods.

Common Questions

Question: Is it possible to specify “original” for the supply of spare parts?
Answer: It is possible if we are talking about a product that is under warranty, or there is a need to ensure the interaction of such goods with goods used by the customer, as well as in the case of the purchase of spare parts and Supplies to machinery and equipment.

Question: Is it necessary to include the procurement identification code in the terms of reference?
Answer: The procurement identification code is indicated in the procurement plan, schedule, notice of procurement, invitation to participate in the determination of the supplier (contractor, performer) carried out in a closed way, procurement documentation, in the contract, as well as in other documents provided for herein Federal law. It is not necessary to indicate it in the technical specification.

Question: You need to purchase a device for scientific research to an existing system of 3 devices from the same manufacturer. It is necessary to completely combine everything in the work. An equivalent is not desirable. Is it possible not to write the equivalent and indicate the manufacturer? The system is highly customizable and expensive.
Answer: If your case fits “...except for cases of incompatibility of goods on which other trademarks are placed, and the need to ensure the interaction of such goods with goods used by the customer...) - it is possible, in other cases - it is not possible.

Question: Is it possible to specify narrow indicators in the terms of reference for major repairs, for example, the color of the walls with a specific color scheme, attach an example of a plasterboard composition on the ceiling, a specific collection of tiles without an equivalent, referring to aesthetic preferences?
Answer: When forming technical specifications, customers must be guided by the requirements of Article 33 of Law No. 44-FZ. The color of the walls is the customer’s choice, it is his need, which does not limit the number of suppliers. A layout, a sketch of a plasterboard composition on the ceiling is also a customer’s need; all performers will be able to repeat the layout given in the documentation. A collection of tiles without an equivalent is a violation of paragraph 1 of Article 33 of Law No. 44-FZ: “The procurement documentation may contain an indication of trademarks if, when performing work or providing services, it is intended to use goods the supply of which is not the subject of the contract. In this case, a mandatory condition is to include the words “or equivalent” in the description of the procurement object.

Remember Murphy's law? If you can be misunderstood, you will certainly be misunderstood. This is true not only in communication between people, but also in creating websites. The client wanted a second Facebook, but got a forum for young dog breeders. The developer did not guess what the customer wanted - he wasted his time.

In this guide I will tell you what and why you need to write in the terms of reference. At the same time, I’ll show you how not to write so that the creation of technical specifications does not turn into wasted time.

The article will be useful:

• For everyone involved in website creation: developers, designers, layout designers.
• Project managers.
• Heads of digital studios.
• Entrepreneurs who are planning to order website development.

To make the material useful, I collected comments from several developers, designers, project managers and owners of digital studios. I added the most valuable ones to the end of the article. Let's go find out.

What is a technical specification and why is it needed?

A technical specification is a document that sets out the requirements for the site. The clearer and more detailed these requirements are, the better all participants in the process understand what it should be like. This means that the chance that everyone will be satisfied with the result increases.

The main goal of the technical specification is to make sure that the client and the contractor understand each other correctly.

There are many benefits from technical specifications. It is different for each side.

Benefits for the client:

• Understand what he pays money for and what the site will be like. You can immediately see the structure, understand what will work and how. Figure out if everything suits you. If not, it’s no problem to change it before development begins.
• See the competence of the performer. If the terms of reference are clear and precise, confidence in the developer increases. If it says porridge, perhaps you should run and not look back.
• Insure against the performer's dishonesty. When the site is ready, it can be checked according to the technical specifications. Are there any inconsistencies? The developer is obliged to fix them. If you are collaborating officially and have entered into an agreement, you can even force it through the courts.
• Simplify the replacement of performers. If the client and the developer quarreled and ran away, the creation of the site can take a lot of time. When there is a detailed technical specification, it can be transferred to a new team - they will get involved in the work many times faster.
• Find out the cost of developing a complex product. It is impossible to immediately estimate the exact timing and cost of developing a complex web service. First you need to understand how the service will work and what functions it will have. For this you need to prepare technical specifications.

Benefit for the performer:

• Understand what the customer wants. The client is asked dozens of questions, shown examples, and offered solutions. Then everything is written down in a single document and agreed upon. If everything is ok - hurray, you understood correctly.
• Insure yourself against the client’s sudden wishes. Sometimes you come across customers who want to change the task halfway through. If you have agreed and signed the terms of reference, you are not afraid of this. If something happens, even the court will be on your side.
• Show your competence. A well-prepared technical specification will show the client the expertise of the developers. If the company doubted whether to trust you with website development, doubts will most likely be dispelled.
• To earn money. Some studios and developers offer the preparation of technical specifications as a separate service.

• Facilitate and speed up the development process. A good technical specification indicates the structure of the site, the necessary functions and elements on each page. When all the requirements are already before your eyes, all that remains is to design and write the code.

Now let's figure out how to create a good technical specification that performs all these functions.

The terms of reference are drawn up by the performer

In general, anyone can draw up technical specifications. “We need a business card website for dental clinic" - this is already a technical task. But will it fulfill its functions? Hardly.

A good technical specification is always prepared by the executor: a project manager or a developer. Obviously, a web developer understands more about creating websites than the owner of a cafe or dental clinic. Therefore, he will have to describe the project.

This does not mean that the client disappears and appears at the very end to write: “Zbs, I approve.” He should also participate in the process:

Of course, the customer can sketch out his own version of the technical specifications. Perhaps this will speed up the process of creating the final technical specifications. Or perhaps the result will be garbage that will be secretly thrown into the trash.

Write clearly and accurately

This advice comes from main goal terms of reference - “Make sure that the client and the contractor understand each other correctly.”

The terms of reference should not contain quality adjectives: beautiful, reliable, modern. They cannot be clearly understood. Everyone has their own concepts of beauty and modernity.

Look. Someone thought this design was beautiful and allowed it to be used on their website:

The same thing happens with vague formulations that don’t mean anything in themselves:

• The customer must like the site. And if he has Bad mood?
• The site should be convenient. What does it mean? Convenient for what?
• The site must withstand heavy loads. 10 thousand visitors? Or 10 million?
• High-quality expert content. Well, you get the idea.

Check for ambiguities in the text. If there is, rewrite it. Your wording should be clear and precise:

• The site must load quickly → Any page on the site must have more than 80 points in Google PageSpeed ​​Insights.
• Heavy loads → 50 thousand visitors at the same time.
• The main page displays a list of articles → The main page displays a list of the last 6 published articles.
• Minimalistic user-friendly subscription interface → “Leave your e-mail” field and “Subscribe” button → *drawn sketch*.

We've sorted out the wording, let's go over the structure.

Please provide general information

All team members must correctly understand what the company does and who its target audience is. So that no one gets confused, it is better to write this down at the very beginning of the terms of reference.

It’s also worth indicating the purpose of the site and describing its functionality in a nutshell - so as not to end up with an online store instead of a blog.

Explain difficult terms

The first rule of the terms of reference is that it must be understandable to everyone for whom it is intended. If you are going to use terms that your client, the owner of a children's toy store, may not understand, be sure to explain them. In clear language, not copy-paste from Wikipedia.

Describe tools and hosting requirements

Imagine that you spent 2 months creating a cool website. Each stage was coordinated with the client - he was delighted. And now it's time to hand in the work. You show the admin panel, and the client shouts: “What is this? Modex?! I thought you would do it on WordPress!”

To avoid such problems, describe the tools, engines and libraries used. At the same time, indicate your hosting requirements. You never know, you will do it in PHP - and the client has a server in .NET.

List the requirements for the operation of the site

The site must work in all current browsers and on all types of devices. Yes, this is obvious to any developer and any customer. But it’s better to write to protect the client from work done in bad faith.

Write here the requirements for site loading speed, load resistance, protection from hacker attacks and similar things.

Specify the site structure

Before you start drawing the design and layout, you need to agree on the structure of the site with the client.

Talk to the customer and find out what he needs. Gather developers, SEO specialists, marketers, editor-in-chief - and decide which pages are needed on the site. Think about how they will be connected to each other, from which one you can switch to.

You can show the structure with a list, you can draw a block diagram. As you prefer.

This is one of the most important stages of working on the site. Structure is the foundation. If it is unsuccessful, the site will turn out crooked.

Explain what will be on each page

The client must understand why each page is needed and what elements will be on it. There are two ways to show this.

Prototype- a more visual and unambiguous way. The contractor draws sketches of each page and attaches them to the terms of reference. The client sees what the interface of his future website will look like and says what he likes and what needs to be changed.

Enumeration of elements- a lazy alternative to prototype. Just write down what blocks should be on the page and what they do.

Describe the scenarios for using the site

If you are making some kind of non-standard interface, just showing the structure and page thumbnails is not enough. It is important that the entire execution team and the client understand how visitors will use the site. Scripts are great for this. The scenario diagram is very simple:

• User action.
• Site response.
• Result.

Of course, if you are making a standard business card or landing page, you don’t need to write scripts. But if there are some interactive services on the site, it is very desirable.

Read more about use cases in Wikipedia.

Determine who is responsible for the content

Some developers create a website with content right away. Others place fish. Still others can write texts, but for an additional fee. Agree on this on shore and write down in the terms of reference what content you should prepare.

It is quite difficult to come up with objective criteria for assessing the quality of texts. It’s better not to write anything other than “High-quality, interesting and selling content that is useful for the target audience.” It's trash, no one needs it.

Specifying that all content must be unique is helpful. Another protection for the client from unscrupulous performers.

Describe the design (if you can)

As with text, it is difficult to come up with objective criteria for evaluating design. If you and the client have agreed on color scheme- write it. If he has a brand book in which the fonts are specified, indicate them too.

Write about beautiful and modern design No need. It means nothing, has no power and generally ugh.

Instead of a conclusion: the structure of the terms of reference

The structure of the technical specifications will be different for different tasks. It’s stupid to make the same technical specifications for a new social network and landing page wholesale carrots. But in general you need these sections:

• Information about the company and target audience, goals and objectives of the site.
• A glossary of terms that may not be clear to the client.
• Technical requirements to the layout and operation of the site.
• Description of the technologies used and a list of hosting requirements.
• Detailed site structure.
• Prototypes of pages or descriptions of elements that should be on them.
• Scenarios for using a non-standard interface (optional).
• List of content that the developer makes.
• Design requirements (optional).

• Rules for compiling Software Requirements Specification. SRS is the next step in the evolution of the technical specifications. Needed for large and complex projects.
• Standards and templates of technical specifications for software development. Descriptions of various GOSTs and methodologies for creating technical specifications.

This is the end of the part that I wrote. But there is another one - comments from specialists who helped make the guide. Read it, it's interesting too.

Developer Comments

I talked to several developers to find out how they create technical specifications. I pass the microphone to them.

First of all, the client needs technical specifications - so that he understands what his website will be like and what the money will be spent on. If something is done wrong, he can refer to the technical specifications and ask for it to be redone.

The technical specification is drawn up by the project manager after communicating with the client and discussing the task with the designer.

Large customers often ask for very detailed technical specifications, which describe each button. Small companies, on the contrary, do not like meticulous 100-page documents. It's a long read and it's easy to miss something important. More often we make concise technical specifications of 10–15 pages.

We indicate:

• Information about the company and the purpose of the site.
• Requirements for design, color scheme.
• Technologies and CMS used.
• Who produces the content - us or the client.
• The structure of the site down to each page.
• Descriptions of each page. We don't make prototypes, but we specify what elements should be on the page and how they should work.

The last 2 sections are the most important. They are the ones who provide an understanding of what the site will be like and how it will work.

A very important point - you can’t just give the terms of reference to the developers and hope that they will do everything well. Technical specification is a list of requirements for the site; it cannot replace communication. It's important to make sure that each team member understands the overall goal and isn't just doing tasks on the fly. If something is unclear, it is necessary to explain, discuss, and give detailed comments.