Technical requirement for creating a system or website - easy about difficult things

Introduction

Most customers are very superficial attitude to the creation of terms of reference (TOR) for the project. They think programmers are not idiots, they must understand the obvious things, and in the process they will understand everything correctly.

In practice, it's a little more complicated:

  • programmers, in their own way, understand how to make a system;
  • new details are identified that require additional time and budget;
  • requirements change as the project progresses (another great idea from the customer that requires immediate implementation).

Economy on the creation of technical specifications eventually leads to large additional costs for processing the system. In some cases, it gets to the point where all the developments are thrown away, and a new solution is made from scratch, with a new team in the hope that everything will be different now. Most likely, it will not be different - the customer is the same, and if they did not make the right conclusions about the development process, then most likely history will repeat itself.

Key ideas on TR

The requester and the developer need the TR

The customer will get exactly what they want, what they have prescribed and agreed in the TR. The contractor clearly understands what they need to do to earn their money. No more, no less.

The TR should be clear to both sides and contain all relevant implementation details.

If the customer does not understand the TR, how is he going to accept work on it? If some details are not described, then everyone will speculate on them in their own way, and this is a great ground for conflicts, misunderstandings and other possible problems on the project.

You don't need to write a technical specification for the entire large system at once

The fact is that by the time you complete it, some requirements will need to be changed/updated. In the process of implementation, ideas may arise. 

The author of the TR, after seeing the implementation, understands that this is not quite the case, and begins to redraw the requirements, which makes everyone very nervous (especially developers). After all, this can dramatically affect the database structure or application architecture.

The best option is to write a basic technical requirements for the first simple version of the program and write a separate development plan for the program.

The program development plan will simply outline the main areas of development without detailed requirements.  Thus, it is described in detail what we will implement in the short term. Developers will also have an understanding of what the customer wants to see in the system in general terms in the future.

Technical requirements are written by the technician in collaboration with the customer

If a single programmer is assigned to create a technical requirement, you will get a very precise TR for a system that no one will use. It will formally work correctly, but it is absolutely useless for business.

If the TR is taken by a customer, a person from a business, then there is an unrelated mess: important details are omitted, there is no application structure, and such a TR is written in a non-technical language (and the TR, in fact, is a guide to action for developers, what needs to be implemented in the end).

Output-the technical requirement is written by the technician based on feedback from the customer. It defines what it wants to implement in terms of business processes and roles, and the IT specialist transfers this to the program interface, data structure, relationships between entities, and so on.

TR is a joint work of two sides.

Sometimes there are situations when one party begins to make claims to the other about "why you didn't warn or didn't notice this trick". In this case, it is necessary to clearly divide the areas of responsibility.
The customer is responsible for determining what we want to do. And the supplier is responsible for how we go through this path. If the direction is initially chosen incorrectly, then no tactical actions will correct the situation. In this sense, the customer's work in the project is much more important than the supplier's work.

In practice, I often see a situation where the customer has a very superficial understanding of what he wants to see in the project and expects the contractor to offer him options, and he will choose.

TR is a great place to say what you want to see in a project. The supplier must develop your vision into a clear, simple interface with the correct data structure.

TR is better to write with the future executor of the system. This way you will save on familiarizing the development team with the business logic. There will be a more accurate understanding of the project and its nuances.

TR - basis for the contract

The TR defines what needs to be done, and this is the basis for the contract for the provision of development services.

Based on the TR, an estimate of work is created and deadlines are determined.

It is very easy to recognize an amateur customer by their desire to determine the exact budget at an early stage, when there is only "Need to make an analog of Amazon".

A good way to build work between the contractor and the customer is to work in stages, where each stage consists of a TR, an estimate for the stage, and a deadline.

A poorly written TR or its absence completely destroys this scheme of work:

  • it is impossible to determine the estimate in detail, the developer will re-order where the requirements are written in general terms (for example, "1C integration");
  • the deadline will probably not be met, as new unrecorded requirements will appear during the work;
  • it will be very difficult to accept jobs. There will be constant disputes about what is / isn't included in the work.

The TR is a working document, not a formality

TR is not created for beauty. It should be written as quickly as possible and with minimal effort, but at the same time contain all the key significant requirements for the system that will allow you to implement what the customer ultimately needed to implement.

There are state STANDARDS for creating technical specifications. But does it make sense to follow them? Many requirements are simply irrelevant, documents are very cumbersome, and creating such technical specifications is a separate large project.

I believe that the TR should solve the main task, and not be formally correct from the point of view of the external standard.

The main task of the technical requirements is to deeply understand what the customer needs, correctly write it on paper and start implementing it as soon as possible.

TR as a description of WHAT + HOW

The TR does not have to contain a purely "what to implement" description. In some cases, it is advisable to immediately work out the question "how" in this document - the details of the system design. This is at contrast with the approach of deliberately distancing the definition of requirements from implementation. TR turns out to be more universal, but this makes us neither warm nor cold. We have other tasks - to understand what the customer wants and implement the system in the shortest possible time.

Everything that is not included in the TR is paid separately

The TR has its own framework.

Anything that goes beyond the frame of the TR is an addition to the task for which a new estimate must be made separately.

The logic is simple-initially, the estimate is based on what is written in the TR. If it is not described there, why should it be paid as if in the TR?

In some cases, I have encountered such a response: "You forgot to include this in the TR, so this is your mistake." First, the technical specification is written jointly, and the customer reads it and approves it before launching it. This behavior is incorrect, to put it mildly. The customer's role in the project should be active and guiding, but not passively waiting.secondly, if the work is not described in the TO, it means that it is not included in the estimate, i.e. it is not initially budgeted.

How we create TR

Next, we will look at our version of creating a technical specification-a system design document for Falcon Space. At the end of the article, you will find a link to a design document template that you can use as a basis for describing your system.

A bit of background. Previously, we used a more complete TR template, where there were many additional sections with terms, "standard requirements" that moved from one document to another. In practice, such "plump" documents only made reading more difficult and blurred the focus on the project. However, the main goal is to implement the system, and not to put the customer in religious awe before 100 pages of the project description, where the basis is described on 10 sheets.

Now we use the most abbreviated version, which allows us to understand what the customer needs to get at the output. And yet the document is written in detail in significant requirements.

Let's go through the sections of our template

General information

They give the contractor (and often the customer) an understanding of what the system is for and what its key feature is.

Who is your user? Here we define who is the user of the system and for what purposes they use it. Knowing this information, you can correctly make accents.
If a user logs in to earn money, they usually don't care about the aesthetics of your design or your unique icons. It is important for them to complete their tasks as quickly as possible and not make mistakes with filling in the data.
There can be several user profiles. We call them roles (Director, operator, cashier, etc.)

What tasks does the user solve? Briefly define the range of user tasks. This list allows you to quickly understand the essence of the system and its purpose.

How does the consumer solve their problem now without the system? This is also important to understand. What added value will the system give to the user? After all, he had been able to do without her before? Why would he switch to it if everything is fine without it? There must be a significant incentive (internal or external). Without understanding the user's incentive, you will simply make a system that no one else needs.

Why is this emphasis on the user? Yes, because it will work in your system.

It is the user who determines the success of the system. No user - no system.

Close all user needs and your system will be on the line.
You can add many more questions about the user, but it is important to maintain a balance - you need to know who your user is and what they need. At the same time, it is important to add only those questions that will affect decisions on the system interface, and not all in a row.

Roles and objects

Define your roles in more detail: who are your users and what their capabilities are in the system.

Identify the main objects in the system. These can be Orders, Products, Customers, and so on. For each object, determine what information you want to store in the system. These can be client characteristics, action logs, statuses, and so on. A detailed description will allow you to take into account all the necessary nuances when creating the database structure in the future.

You don't have to take everything into account the first time. In the course of working on other blocks, you will still be adding something. 

Act iteratively, describe the basics, move on and add features as new information becomes available.

Business processes

Identify the main business processes. Start with the main ones.

Consider the following points in the process description:

  • Describe the basic sequence of actions. In the case of complex processes with branching logic you can make a flowchart.
  • Use the artifacts. An artifact is some kind of physical evidence that another action was performed. This can be a log entry, a document, a notification, or a brand (a joke).
  • Don't make the new process too complicated. It is better to implement a simple process first, and then gradually Polish it and modify it as necessary. The process described is difficult to implement, difficult to implement and redo.
  • Specify for the process what is the factor, trigger, and output result. The trigger starts the process, the actor performs the main work in the process, and the result is an artifact at the output after all the actions of the process are completed.

In my opinion, in terms of describing processes, it is much more important to describe them correctly than the form itself.This can be a simple list of sequential actions.

Don't get carried away with process design tools. The simpler the form, the easier it is to change these processes and the easier it is to read them to other project participants.

If the text in the project is too smart or written in a specific language and only you understand it, then this description is useless. Moreover, there will be significant harm. The project seems to have a good description of the processes, but no one actually uses it.

Also in this section, it makes sense to describe the key limitations of business logic that performers should pay attention to (for example, that an Employee can be linked to a single management).

Project structure and pages

This is the most important section for the performer. This is where we describe exactly what you need to implement on the app's pages.

First - describe the structure of the roles in the form of a table. There is an unauthorized area (where anyone can go) and an account for each role.
For each page, specify a URL and a short description. This table is essentially a map of the entire project, a kind of skeleton of the application.

After defining the app structure, we describe each page in more detail. We use our Falcon Space platform for development, and this determines our way of creating pages (placing components). We immediately specify a more precise link to our components in the page requirements - this speeds up the task execution process (you don't need to additionally describe how to implement a particular functionality, i.e. create an additional document of comments to the TR for the developer).

The description of each page can contain the following elements:

  • What we display on the page: tables, forms, which columns, which buttons will be available, whether there will be modal forms, sub-tables, comments. As detailed and specific as possible.
  • Actions of the control buttons. How a particular button should work. What changes in the state of objects. What is displayed to the user in case of success/failure of the operation. What checks should be made, etc.
  • Access restrictions. Who has access to the page. Are there specific access restrictions (not just by role, but, for example, only the author of a task can change its deadline).
Any inaccuracy in the description of pages is a reason for a dispute between the customer and the contractor.

Therefore, try to describe everything in clear, simple language, but as specific as possible.

Integrations

You need to define a list of external systems to integrate with. For each integration, you need to define the following points:

1. What data should be transmitted between systems and in which directions. You don't need to write just "integration of everything and everything". You need specific data, and that's what you need to define. It is desirable to determine the exact format of the data itself, not just the transfer of the Product, but the transfer in the form of a JSON structure.

2. In what format and Protocol data will be transmitted, for example, using GET requests over the HTTPS Protocol using the JSON format.

3. It is better to determine in advance whether an external system can integrate with your system, i.e. determine its integration capabilities, and from this you need to build your own API for interaction with this system.

4. The API is an additional uncertainty factor. In the case of integration with an unknown system in the TR, it makes sense at the first stage to lay down just the development of the API prototype to understand the main features of integration. Otherwise, if the customer wants everything at once, the developer must re-assign these risks of problems arising from a third party (external API provider).

Possible extensions

This is a plan for future possible improvements to the program. These can be various integrations, new modules, or cabinets.
This information allows the developer to understand what they should expect in the future regarding the development of the system. This insures us against the risk that somewhere in the middle of the project it will turn out that it is difficult to implement a critical opportunity on this solution.

Database design

This is an element of the system implementation. Here you can specify the initial structure of the database - tables with columns, table relationships, indexes, keys, and so on.

Why is it good to do this early? In this case, you can show an external specialist the database structure and get some feedback. Problems with incorrect database structure are very critical. Therefore, it is best to correct them at the very initial stages, when the database itself has not yet been created, or when there is not enough data in the database.

The database will tell the technical specialist about the main objects of the system and the relationship of these objects. It is also useful to describe key relationships in text, for example, a Product may belong to different Categories, or Categories may be nested into each other on 3 levels.

Conclusion

We touched on the main elements of creating a TR, described the composition of our template, and also understood the key beliefs about the process of creating a TR.

Of course, a good technical requirement is not a guarantee of a good project implementation. But we can say for sure-without a clear vision of the project and a clear description of what needs to be done (and this is essentially the TR), there is a very high probability that the project will not even reach the implementation stage. There will be constant reworking, spontaneous ideas, disputes and conflicts with developers about "it's obvious", their change, search for new ones, etc.

Put a strong emphasis on working out the TR at the beginning of the project, and this will solve a lot of future problems during the project (rework, disputes, going over budget).
Template for a design document of the project

The author of the article is Ruslan Ryanov

The creator of the Falcon Space platform

Falcon Space Platform

This is a reduction in the cost of ownership

at the expense of fewer people to support

This is a quick change

while using the program

This is a modern interface

full adaptation for mobile devices

Component demo stand
At the stand you can see various components in action - tables, forms, modal windows, diagrams, a map, etc.
Solution demo site
Basic solutions that can be flexibly adapted for yourself - change the appearance, business logic and even the structure of the database.
Discuss the project
Ask the initial questions about the project that concern you right now. We will advise you for free and recommend the best solution.

If you like our articles, then please subscribe to our channel in Telegram - Falcon Space.
In it we will publish updates on articles and other materials regarding our platform.