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.
Benefits for the performer:
- Understand what the customer wants. The client is asked dozens of questions, shown examples, and offered solutions. Then they write everything down in a single document and agree on it. 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 a 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 follows from the main goal of the 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. What if he is in a 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 browsers current versions 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 what 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 to be 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 assessing website design. If you and the client have agreed on a color scheme, write it down. If he has a brand book in which the fonts are specified, indicate them too.
Write about beautiful and modern design No need. It doesn't mean anything, 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 a landing page for the wholesale sale of 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 for 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.
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 to have seven mutually perpendicular lines, and also draw some in red, and draw some in colorless (I recommend watching a video about this topic at the end of the material).
Design department
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 site) or 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”, 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:
- Description of the project/task. We briefly write what the project or task is that needs to be completed.
- Purpose and goals. What are the goals for the project?
- Requirements. Design, functions, technologies that are needed.
- Description of work. What, when and how will be done.
- Control and acceptance procedure. How the work will be accepted, what can be considered completed.
- Applications. Sketches, sketches, prototypes.
The cost of the work is usually included in a separate appendix 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. 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”:
- Description: you need to create a “Like” button on our website.
- Purpose and goals: user involvement, issuance/rating of materials based on the number of likes.
- Requirements: the following design (example: a link to something similar), functionality (any user can rate the 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 of the site).
- Description of work: draw 3 options for button layouts (ready date: 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)
- Acceptance of work: the user presses the like button, the system counts the click, the delivery of materials changes.
- 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.
How to write a technical specification for a program according to GOST 19.201-78?
Created 02/15/2010 15:50:53
Note dated June 11, 2014 - Dear ladies and gentlemen! Probably, every second or third of your technical specifications for programs, which in one way or another ended up in the hands of the author, contains authentic texts from this article. This is great and damn nice, but you have to take into account the fact that almost a decade has passed since the first article, and during this time a lot has changed, especially in the part. Of course, you can’t erase the words from the song, but be creative and come up with some more modern arrangements. And do not forget that this is not a “” document.
Technical specifications in accordance with sheets of format 11 and 12 according to GOST 2.301-68, as a rule, without filling out the sheet. Sheet (page) numbers are placed at the top of the sheet above [from clause 1.1 of GOST 19.201-78]
Approval Sheet and Cover Sheet
Leaf and title page drawn up in accordance with GOST 19.104-78.
The information part(s), the change registration sheet may not be included in the document [from clause 1.2 of GOST 19.201-78]
This opportunity should be taken advantage of. Fewer words - fewer questions.
Changes and additions
To make or addendums to the technical specifications on subsequent ones, or issue an addendum to it. and additions to the technical specifications are carried out in the same order as established for the technical specifications [from clause 1.3 of GOST 19.201-78]
It is impossible to take into account all the details at the initial stage, so in practice this approach is used quite often. In “Stages and stages of development” the possibility of making changes and additions to the technical specifications should be clearly indicated: “The content of sections of this technical specification can be changed and supplemented by agreement with the customer.”
Composition of sections of technical specifications
The terms of reference must contain the following:
- introduction;
- reasons for;
- purpose of development;
- to or;
- requirements to;
- technical and economic indicators;
- order and;
- Applications may be included in the technical specifications.
Depending on the features of the program or software product, it is possible to clarify the content of sections, introduce new sections or combine individual ones [from clause 1.4 of GOST 19.201-78]
Any manipulations with sections are strictly according to p.
Certain subsections of the technical specifications can act on a conditional customer like a red rag on a bull. The customer, even a conditional one, should not be irritated. In controversial subsections, ways to find compromise solutions will be considered. Key positions in which a concession to the customer is tantamount to tightening a noose around the performer’s neck will also be commented on, justifying the performer’s tough position.
In order not to unnecessarily burden the flow of the narrative, we will use real program s, providing the ability to perform several template functions. Let such a program become uncomplicated.
Introduction
In the “Introduction” section, indicate a brief description of the scope of application or the object in which the program or software product is used [from clause 2.1 of GOST 19.201-78]
The basic rule of working with is detailing, breaking up the text into structural units - sections, subsections, paragraphs and subparagraphs, see article "" The document will have a clear structure that facilitates the ease of the required material. The text of the document will become structured and easy to read. Create subsections:
Program name
The name of the program is “Text editor for working with rtf files.”
Brief description of the field of application
The program is intended for use in specialized departments at customer sites.
The content of individual items is not always obvious. If you have any difficulties, you should approach them formally. The document will be available during the technical assignment with the customer.
Reasons for development
The section “Basis for development” should indicate:
- document(s) on the basis of which the development is carried out;
- , this document, and the date of its approval;
- and (or) symbol of the development topic.
[from clause 2.2 of GOST 19.201-78]
Basis for development
The basis for the development is Agreement (letter, etc.) No. 666 dated March 32, 2004 (incoming No. such and such from such and such). The agreement was approved by the Director of the FSUE "Spetstyazhmontazhstroyselkhozavtomatika" Ivanov Petr Ivanovich, hereinafter referred to as the Customer, and approved by the General Director of OJSC "Supersoft" Blyumkins Ivan Aronovich, hereinafter referred to as the Contractor, on such and such March 2004.
It is convenient to use the “General Information” section, since the developer has every right to add and delete sections of the technical specifications at his own discretion. At the same time, the information specified above is contained in the contract. Whether they should be included in the technical specifications depends on the specific case.
Name and symbol of the development topic
The name of the development topic is “Development text editor for working with rtf files." Symbol of the development topic (topic code) – “RTF-007”
Purpose of development
In the section “Purpose of development” the operational purpose must also be indicated or [from clause 2.3 of GOST 19.201-78]
Functional purpose
The functional purpose of the program is to provide the user with the ability to work with text documents in rtf format.
The subsection should indicate the “enlarged” functional purpose of the program. Details – list of functions, etc. - will be given below in the relevant sections.
Operational purpose can be interpreted quite broadly. Where, how, by whom, with what should the program be used?
Tires of the same size can be successfully used on Zhiguli and Volga vehicles, but not on KamAZ. Due to absence. And vice versa. But for each specific rubber size, its operational purpose can be determined.
Let's use a formal approach:
Operational purpose
The program must be used in specialized departments at customer sites. employees of specialized departments of the customer’s facilities must appear.
The two extreme sentences are off topic. During negotiations with a real customer, the subsection will be adjusted.
Requirements for a program or software product
The “Requirements for a program or software product” section should contain the following subsections:
- requirements for functional characteristics;
- requirements to;
- requirements for composition and parameters;
- requirements for and;
- requirements for and;
- requirements for and;
- special requirements.
[from clause 2.4 of GOST 19.201-78]
If there are standards containing general (technical) requirements for the program, or, for example, “GOST 12345-67. Automated information and measurement systems. General (technical) requirements”, the development of technical specifications is significantly simplified. Most of the contents of the specified standard are simply rewritten into the technical specifications.
Requirements for the composition of functions performed
The program must provide the ability to perform the following functions:
- functions for creating a new (empty) file;
- functions for opening (loading) an existing file;
- functions for editing an open (hereinafter referred to as the current) file by entering the contents of the file using standard ones;
- functions for editing the current file using;
- source file functions;
- functions for saving a file with a name different from the original one;
- functions for sending the contents of the current file by email using an external client mail program;
- functions for displaying online information (tips);
- functions;
- functions for displaying the program name, program version, copyright and developer comments.
The cliché “enable execution” applies to modern software, developed using a graphical user interface. These software tools are mostly “idle”, waiting. The use of cliches - template construction of phrases - is described in detail in the article "".
Requirements for organizing input data
programs must be organized in the form of separate files in rtf format that comply with RFC... Files of the specified format must be placed () on local or removable, according to the requirements operating system.
Anything else, but with the rtf extension, should not be opened.
The files http://domain.net/file.rtf or ftp://domain.net/file.rtf should not be opened. If file system formatted as FAT32, files from a local or removable file formatted, for example, in ext3 format, should not be opened.
Requirements for organizing output data
The requirements are the same as for organizing output data. This is the very case when both points of the technical specifications should be combined.
Timing requirements
There are no requirements for the timing characteristics of the program.
It is necessary to clarify whether the customer has requirements for the speed of the program, for example, in what time the program should start, open and close files of a given size. If the customer specifies specific numbers, you should be on the safe side and include it in the requirements for the composition and parameters of technical equipment costing $2,500 or more. True, such an amount will have to be justified. If time characteristics are not important for the customer, you should definitely write about the waiver of requirements for time characteristics, see the wording above.
Reliability requirements
The subsection “Reliability Requirements” must indicate the requirements for ensuring operation (support, control of input and output information, after, etc.) [from clause 2.4.2 of GOST 19.201-78]
- it’s a delicate and very dangerous thing. But the list of functions and their types, according to clause 1.3.2. , must be drawn up by the customer and agreed upon with the contractor.
Most likely, you won’t be able to expect anything intelligible from the customer. It is worth explaining to the customer that the reliable operation of the program depends not so much on the performer, but on the reliability of the technical means, and also to offer the customer a number of stringent measures to increase and.
Requirements for ensuring reliable (stable) operation of the program
Reliable (sustainable) operation of the program must be ensured by the customer’s implementation of a set of organizational and technical measures, the list of which is given below:
- organization uninterruptible power supply technical means;
- use of software;
- regular implementation of the recommendations of the Ministry of Labor and Social Development of the Russian Federation, set out in the Resolution of July 23, 1998 “On the approval of inter-industry standard time standards for work on service PCs and office equipment and software support";
- regular compliance with the requirements of GOST 51188-98. Information protection. Testing software for availability.
You can add dozens more to the list. During the initial approval of the technical specifications, the customer will most likely begin to show a tendency to compromise.
A more humane approach is possible. Reliability (of a system, according to the same GOST) can be considered the performance of a certain i-th function during a specific time interval. We suggest that the customer consider the following indicator as a criterion for the reliable operation of the program: the customer opens and closes the file 100 times within an hour. If the program does not respond within the specified time interval, it is considered completed.
If the customer is finally convinced that reliability depends not so much on the performer, but on the reliability of the hardware and operating system, and gives up, the following phrase must be written in the section:
There are no requirements to ensure reliable (stable) operation of the program.
Recovery time after failure
Caused by a power failure of hardware (other external factors), not a fatal failure (not crash) of the operating system, should not exceed so many minutes, provided that the hardware and software are followed. The recovery time after a failure caused by a malfunction of hardware or a fatal failure (crash) of the operating system should not exceed the time required to eliminate hardware and reinstall software.
The list of emergency situations is also compiled by the customer and agreed upon with the contractor. In fact, this is the time to reboot the operating system, if the failure is not fatal, is not caused by the crash of the operating system or failure of hardware.
Failures due to incorrect operator actions
Program failures are possible due to interaction with the operating system. To avoid program failures for the reason stated above, you should ensure that the user can work without providing him with administrative permissions.
terms of Use
The subsection “Operating conditions” must indicate (relative humidity, etc. for selected types) under which the specified characteristics must be ensured, as well as the required number of personnel [from clause 2.4.3 of GOST 19.201-78]
A very dangerous subsection for those who are taking their first steps in developing technical specifications.
Climatic operating conditions
The climatic operating conditions under which the specified characteristics must be ensured must satisfy the requirements for technical means in terms of their operating conditions.
The program will work perfectly from plus 5 to plus 35 °C with a relative humidity of 90% and an atmospheric pressure of 462 mmHg, since such conditions approximately correspond to operating conditions modern computers non-industrial execution. But as soon as the technical specifications contain specifics and the task is approved, the customer gets an excellent chance to force the contractor to carry out the work in full at the contractor’s expense.
Many years ago, the author of the article, due to his youth and an indomitable desire to defend his position (in the technical specifications, in particular), “fell into climate change”, and “fell specifically” (as, according to Putin, the enlightened intelligentsia puts it), quite cool hardware. The author of the article instantly learned what it meant to “show Kuzka’s mother” and “where the crayfish spend the winter.” God forbid you get caught in climate change!
Note from 02/10/2011 - Ironically, the specialists of “Technical Documentation” not so long ago “got into climate control” again, or rather, they developed a program and testing methodology for the influence of external factors, and then prepared it, discovering another one. It’s not for nothing that they say that history develops in an upward spiral...
Requirements for types of services
The program does not require any type of testing.
Types of maintenance should be borrowed from the subsection “Requirements for ensuring reliable (sustainable) operation.”
If the customer, during the approval of the technical specifications, refers to the absence or desire to carry out all types of maintenance on their own, it makes sense to offer the development of technical specifications for a separate fee under a separate contract. If he refuses, the program should be considered.
Requirements for the number and qualifications of personnel
The minimum number of personnel required for the operation of the program must be at least 2 staff positions - a system administrator and a program user - operator.
The system administrator must have a higher specialized education and the operating system manufacturer. The list of tasks performed system administrator, should include:
- the task of maintaining technical means;
- tasks of installation (installation) and maintaining the functionality of system software - the operating system;
- the task of installing a program.
The program user (operator) must have practical skills in working with the operating system.
Personnel must be certified for qualification group II in electrical safety (for working with office equipment).
In the absence of the key phrase in the approved technical specifications, the customer has the right to request that the contractor develop a manual for operating the graphical user interface of the operating system, arguing that the operator “cannot cope” with the program.
Personnel who do not have qualification group II in electrical safety do not have the right to even come close to office equipment.
Requirements for the composition and parameters of technical means
In the subsection “Requirements for the composition and parameters of technical means” indicate the required composition indicating their main technical characteristics[from clause 2.4.4 GOST 19.201-78]
It should be selected no worse than the one on which the development will be carried out. It is logical to request that the customer provide the equipment no later than the specified period. We are talking, of course, about a computer.
The hardware must include an IBM-compatible Personal Computer(PC), including:
- Pentium-1000 processor with a clock frequency of 10 GHz, no less;
- motherboard with FSB, GHz - 5, no less;
- RAM capacity, TB - 10, no less;
- and so on…
Requirements for information and software compatibility
The subsection “Requirements for information and software compatibility” should indicate the requirements for information structures at the input and output and solutions, and used by the program.
If necessary, it should be provided [from clause 2.4.5 of GOST 19.201-78]
Requirements for information structures and solution methods
The information structure of the file must include text containing that provided for by the rtf format specification.
There are no requirements for information structures (files) at the input and output, as well as for solution methods.
Requirements to source codes and programming languages
The source codes of the program must be implemented in C++. The Borland C++ Buider environment should be used as an integrated program.
Requirements for software used by the program
Used by the program must be represented by a licensed localized version of the operating system of such and such. It is acceptable to use such and such an update package.
Requirements for the protection of information and programs
There are no program requirements.
Such requirements should be avoided unless there is a special desire to develop something like a concept for ensuring information security according to It is possible to ensure a certain level of programs, but it is impossible to ensure security. The customer will most likely realize this and will not persist.
Labeling and packaging requirements
In the subsection “Requirements for marking and packaging”, in general, the requirements for marking, options and methods of packaging are indicated [from clause 2.4.6 of GOST 19.201-78]
The program is supplied as a software product - on a distribution (external) medium (CD). We are talking, of course, about the labeling and packaging of the distribution.
Labeling requirement
The software product must be marked with the designation of the developer company, type (name), version number, serial number, date of manufacture and Gosstandart number of Russia (if any). The marking must be applied to the software product in the form of a sticker, made by printing, taking into account the requirements of GOST 9181-74.
The quality of the marking is checked using the most sophisticated methods - first they try to wash off the marking with water, then with gasoline and other organic solvents. Let the printing company bear responsibility for poor quality labeling. The performer’s task is to hide behind a certificate of conformity (to request a certificate from printers).
Packaging requirements
The software product must be packaged in packaging containers ().
Precisely the manufacturer (supplier). The contractor cannot and should not bear greater responsibility than the manufacturer (supplier) of the container.
Packing conditions
Packaging of the software product must be carried out in closed ventilated areas at a temperature from plus 15 to plus 40 ° C and a relative humidity of no more than 80% in the absence of aggressive impurities in the environment.
The customer will receive the software product in proper appearance. If the software product is returned in improper condition (scratches, cracks, etc.), the contractor will be able to make claims regarding the customer’s violation of the packaging conditions and not accept the software product.
Packing procedure
Software products prepared for packaging are placed in containers, which are boxes made of corrugated cardboard (GOST 7376-89 or GOST 7933-89) according to the drawings of the packaging manufacturer.
The software product is packaged using covers made of waterproof film with the obligatory presence of chemically non-aggressive desiccant (silica gel).
For filling free space Gaskets made of corrugated cardboard or foam plastic are placed in packaging containers.
must be placed in consumer packaging along with the software product.
A packing list and a packing list are placed on the top layer of cushioning material.
Consumer packaging must be covered with adhesive tape 6-70 in accordance with GOST 18251-87.
Software products packaged in consumer packaging must be placed on a pallet, tied with tape to prevent loss of shape of the cargo, and packaged in polyethylene film M 0.2 to protect against moisture.
The pallet box must contain shipping documentation, including a packing list in accordance with GOST 25565-88.
The dimensions of the cargo space must be no more than 1250 820 1180 mm.
NET weight - no more than 200 kg.
GROSS weight - no more than 220 kg.
The packaging order from a previously developed document for some technical means. It looks somewhat unusual in the context of a software product. In simple Russian, it’s complete banter, but the demands are and remain demands.
Transportation and storage requirements
In the subsection “Requirements for transportation and storage” the conditions, locations, storage conditions, storage conditions, in various conditions should be indicated [from clause 2.4.7 of GOST 19.201-78]
The subsection provides the conditions for transportation and storage from a previously developed document for some technical equipment. This also applies to packaging requirements. It looks somewhat unusual in the context of a software product.
The customer has no right to violate the conditions of transportation and storage. The Contractor will be able to refuse to return the software product to the customer, claiming that the appearance software product is a consequence of non-compliance with transportation and storage conditions.
Transportation and storage conditions
It is allowed to transport the software product in a transport container by all types of transport (including in heated sealed compartments of aircraft without distance restrictions). When transported in railway cars, the type of shipment is small, low-tonnage.
When transporting and storing the software product, protection against ingress must be provided. It is not allowed to tilt the software product. Climatic conditions for transportation are given below:
- ambient air temperature, °C - from plus 5 to plus 50;
- , kPa - such and such;
- relative air humidity at 25 °C is such and such.
Special Requirements
The program must provide interaction with the user () through a means developed in accordance with the recommendations of the operating system manufacturer.
The developers of this standard looked to the future. There were no programs with a graphical user interface in those years.
Requirements for software documentation
The section “Requirements for software documentation” should indicate the preliminary composition and, if necessary, special requirements for it [from clause 2.5a of GOST 19.201-78]
Preliminary composition of program documentation
The software documentation should include:
The test program and methodology will be required to show the customer that the program developed by the contractor meets the requirements of the agreed and approved technical specifications. After joint (acceptance) tests, the customer and contractor will sign. And, thus, the work will be closed, the terms of the contract will be fulfilled.
It is allowed to combine certain types of operational documents (with the exception of and). The need is indicated in. The merged document is also assigned the designation of one of the merged documents. The merged documents must contain information that must be included in each merged document [from clause 2.6 of GOST 19.101-77]
But for those who are starting to develop software documentation for the first time, it is better to adhere to the principle of “separate flies, separate cutlets.”
Technical and economic indicators
The section “Technical and economic indicators” should indicate: approximate economic, estimated annual need, economic advantages of the development in comparison with the best domestic and foreign samples or analogues [from clause 2.5 of GOST 19.201-78]
Estimated economic efficiency is not calculated. The estimated number of program uses per year is 365 work sessions at one workstation.
Let’s say a customer equips a dozen workstations with the program. The contractor demanded $1000 for the development. The customer could install a software product from a third company on the workstations, costing $500 for the distribution kit and $100 for the license for each workstation.
Economic benefits of development
The economic advantages of the development in comparison with the best domestic and foreign analogues will be:
number of jobs | development | economic benefits |
|
Types of tests
must be carried out at the customer’s site within the time frame...
Acceptance tests of the program must be carried out in accordance with the “Program and test methods” developed (no later than such and such a period) by the contractor and agreed upon by the customer.
The progress of the acceptance tests is documented by the customer and the contractor.
General requirements for acceptance of work
Based on the test report, the contractor, together with the customer, issues an acceptance and commissioning certificate for the program.
Applications
In the appendices to the technical specifications, if necessary, the following is given:
- a list of other works justifying the development;
- diagrams, tables, descriptions, justifications, calculations and other documents that can be used during development;
- other development sources.
[from clause 2.8 of GOST 19.201-78]
If there is, why not bring it. And be sure to post a list of GOSTs on the basis of which development should be carried out. For example:
- GOST 19.201-78. Technical specifications, requirements for content and design;
- and so on..
conclusions
This standard, despite its considerable age, allows you to develop a full-fledged technical specification for a modern program with a graphical user interface. The developers of GOST 19.201-78 looked to the future and took into account almost all aspects related to the development of software.
What's left unaccounted for? Terms, volumes and stages of financing? Terms of reference are always developed on the basis of an Agreement, letter, etc. The specified information must be reflected in the Agreement.
What are the controversial points? The absence of specific requirements in the standard, for example, for the user interface? The developers of the standard provide a section “Special requirements”, the ability to add new sections, for example, sections “Additional requirements” or “Interface requirements”.
- GOST 19.201-78 Unified system of program documentation. Technical task. Requirements for content and design
The terms of reference are important for both the contractor and the client. It helps the contractor to better understand what the customer wants, to insure against sudden “wants” on the part of the client, and to speed up the work on completing the task. The client can be told exactly what he wants, simplify quality control, and receive the exact cost of the service. We will talk about how to correctly draw up technical specifications and what to do with it later.
What is a technical specification
Technical specifications are a document that reflects all the requirements for the future product. It describes all technical requirements. Typically, technical specifications are compiled in the form of a text document, rarely in other formats.
TK is used by all website developers. It helps layout designers, programmers, and designers to better understand the client’s requirements and create a resource that meets their expectations. In addition, technical specifications are used in all other areas, for example in:
- application development;
- house design;
- writing texts and others.
If you work according to technical specifications, the risk of disputes and protracted litigation is minimized.
How to draw up technical specifications: structure of technical specifications for a website
Before you start:
- Decide who will draw up the technical specifications
- Explain the terms
- Avoid subjective terms
At first glance, it seems that the technical requirements for the site should be drawn up by the client, because he orders a resource and puts forward requirements for it. In fact, both should participate in the process: the client voices the requirements, and the performer writes them down specifically, accurately and clearly. For example, a client says that he wants a website adapted for all users, and the developer specifies requirements for adaptability for 4 available sizes - PCs, laptops, tablets, smartphones.
Clarification of terms is a very important point. It is advisable to explain all highly specialized terms at the very beginning - clients do not always know what a footer, CMS, or fish is. The simpler and clearer the explanations are, the clearer the technical specifications will be for both parties.
Subjective terms can cause unnecessary controversy. Don’t write “design should be beautiful” - everyone’s concept of beauty is different. The same applies to qualitative adjectives “convenient”, “easy to use”, “large”. Use specific numbers and parameters: for example, describe the color scheme or arrangement of elements.
The structure of the technical specifications can be any. As an example, we offer a simple structure of terms of reference for a website.
Describe the site
Tell us what type of site is needed, who will use it, and why it is being created. For example, write that you need an online store, a landing page for selling a product, or a business card website with 10 pages. Please indicate the approximate number of pages if you do not know the exact number.
If the project has a specific target audience, describe it. This will help you create a resource that will appeal to customers - for example, using appropriate language in articles or a design that appeals to young people or older generations.
Tell us about the structure
Without an idea of the structure, it is impossible to develop a normal website. Describe what pages will be on the site and show the levels of their nesting. This can be done in different ways:
- Scheme
- Table
- List
The main thing is that in the end it is clear which pages will be located in the menu, where they will lead, and which parent page is for each section. We recommend using flowcharts - they are simpler and easier to understand than lists and tables, and help you evaluate the entire structure of the site in a few seconds.
Example simplest structure in the form of a block diagram Describe what will be on each page
Tell us how you see the site's pages. It is advisable to do this in prototype format to clearly demonstrate the location of each element. You can describe the requirements with a list, for example, tell what will be in the header of the site, where the feedback form is located, what will be in the free side column.
If all the pages of the site are approximately similar - for example, you are planning to create a business card website, you can get by with two prototypes: for home page and other sections. If there are several groups of similar pages - for example, sections in an online store catalog, a blog with articles and a description of delivery/assembly/installation services, it is better to make your own prototype for each group.
An example of a website home page prototype: everything is simple, convenient, understandable Set design requirements
If you have a developed layout, great - you can simply insert it into the technical specifications. If not, you need to describe the requirements for the color scheme, images used, and logos. For example:
- Indicate which corporate colors can be used in the design and which shades absolutely cannot
- Provide a logo, which must be present in the site header
- Specify the fonts that you would like to use for pages, menus, footers, and content
If there are no clear requirements - that is, the client himself cannot formulate his vision of the site, you can offer him several standard layouts to choose from or develop a layout individually, and then agree on it. This must be done before the technical specifications are approved, otherwise the difference in tastes can significantly delay the project.
Describe the requirements for tools, code, hosting, domain
This is necessary to know in advance which tools you can work with and which you cannot. Describe in a separate block:
- Which site should the site be on - WordPress, Joomla, Modex, etc.
- What programming language can be used - PHP, JavaScript, HTML, others
- On what hosting and in what domain zone should the site be located? Domain name can be used
- What software platform can be used - .NET, OpenGL, DirectX
- And so on
If the client does not understand anything about the terms used, explain the difference between WordPress and Modex, PHP from HTML, a domain in zone.ru from a domain in zone.com. Together, draw up the requirements so that they suit the client.
Specify the site operation requirements
By default, the site should work for users of all devices, in different browsers, and withstand hacker attacks and do not lie down when 1000 users visit simultaneously. But it’s better to write this as a separate block. Please indicate:
- Website loading speed that is acceptable to you or the standard value is 1–5 seconds
- Cross-browser compatibility - specify in which browsers the site should open
- Responsiveness - specify the screen sizes that the design should adapt to and the devices used
- Resistance to loads - how many people should be on the site at the same time so that it does not “go down”
- Resistance to hacker and dDos attacks: the site must withstand small attacks
Write down the site operation scenarios
Describe how the user should interact with the site, and what actions on the resource should occur in response. This can be done in the form of a simple numbered list or a branched algorithm if users have a choice between actions. If there are many interactive services, write a scenario for each of them.
An example of the simplest scenario for a website Find out who is producing the content.
Some developers write texts themselves, some order them from copywriters, others use fish. Please immediately clarify whether the provision of content is included in the development service. If yes, you can immediately specify additional requirements, for example, for:
- - no less than 95% according to Advego, Text.ru, Content.Watch
- Nausea (spamming) - no more than 10% according to Advego or 65% according to Text.ru
- Points according to Glavred - at least 6.5 or 7 points
Certainly, different services- not a panacea, but they minimize the risk that it will be “watery” or over-spammed. In addition, this is how precise criteria for assessing the quality of texts appear.
Specify deadlines
This is often forgotten. Most technical assignments must specify deadlines, otherwise development may drag on for several months, six months, or years. Do not use incorrect wording - for example, “in a month.” Write the exact date: December 1, 2018, for example.
Lifehack: it is better to draw up the terms of reference as an annex to the cooperation agreement. This way you establish all the requirements for website development, and in case of disputes you will be able to win the case in court.
Remember: each technical specification must contain several main blocks:
- Goals and objectives - about why you created the technical specifications in general, what you want to do with the product
- What should the product be like - description in general terms
- Technical requirements - area of the house, volume of text, application functionality, etc.
- Deadlines - they are important to avoid disputes.
An example of drawing up technical specifications for software
We need to create software. Technical requirements are below.
Description: a program for searching articles by keyword on all authoritative sites; the addresses of authoritative sites must be entered manually.
What the software should do:after entering keyword finds articles on sites that have been entered in advance as authoritative sources, displays a list of matches in this format:
- Link
- Article title
- Lead paragraph
If there are more than 10 matches, you need to divide it into pages - 10 on each.
Technical requirements:programming language - any, it doesn’t matter. The main thing is that the program can then be modified and released as an online service. Ideally, the service should search in 10 seconds.
Deadlines: until September 15, 2018.
Naturally, this technical specification can be improved - we provided it as an example. How do you think the terms of reference can be improved to make it even clearer, simpler, and more convenient?