How much does 1 kilogram of TK weigh?


What weighs more – 1 kg of TK according to a template or 1 kg of TK according to guidelines?


Hey! Don’t be scared, I completely agree with you, the first reaction to the headline should be like Jackie’s. Now I’ll tell you everything in order. And in the end, we even really weigh the two types of TK.

I am again in touch, Sergey Pavlov, team leader for system analysis at Otkritie Bank. As I wrote earlier, we developed a kind of paradoxically named “strict flexibility technique for writing TOR”. That is what I want to talk about today.

First of all, I want to note one important detail that has changed over the year – our team of system analysts at the SME “Business Portal” project has increased from 12 to 25 people (there should be a picture with rabbits, but something went wrong).

Such growth entailed a lot of changes in internal processes, including in the process of writing/preparing terms of reference for development.


So what we had:

  • Several types of well-established record keeping rules;

  • One template (“fish”) for writing TK;

  • A few examples of written TK according to the template.

What I would like to get as an output:

  • Single style TK;

  • An intuitive tool for describing development tasks;

  • The document should be easy to read and understand by any end user (developers, analysts, etc.).

First, we tried the simplest and most banal method “now let’s create a TK template. It’s simple! I took it, corrected it, removed the excess and you’re done. What’s so complicated?”.

Just do it. © Nike


TK according to the template

Let’s try! They brainwashed, threw in points, it turned out the following – the document is not written from scratch, but according to the same template, which in turn is a kind of mixture of “fish” and “filling instructions”.

The template consisted of 14 points, which, if necessary, need to be filled in (the extra ones are deleted at the same time):

  • Link to UserStory – we attach a link to the UserStory, within which the work takes place;

  • Coordination – this was just discussed in the last article, where we indicate the list of participants and control the understanding of the task by all performers;

  • Target – briefly describe the purpose of this TK / CHTZ;

  • Integration interaction – we attach links to articles where we describe any internal and external communications;

  • Access – data for connecting to external systems;

  • Glossary – in fact, the glossary itself, or a link to general terms;

  • Design – links, layouts, etc.;

  • backend – changes in the database, changes in the API;

  • front end – scenarios of behavior and system interaction;

  • Mapping for data bus – scheme, attribute composition of integration;

  • Error processing – description of the system behavior in case of errors;

  • Testing – We focus on some scenarios, preconditions and the expected result. IMPORTANT! Do not forget to clarify whether load testing will be needed;

  • Restrictions – technical limitations in implementation, i.e. explanation of the reasons why something cannot be done;

  • Useful Documentation – a section for documents that may be useful.

It seemed to be an iron and proven method. Strong position, rilli sense and all that. As Mr. Urgant says: “We are working!”.

We tried to write a few technical requirements a little with a creak and realized that we needed to expand the template further. Not everything that I wanted to say fit into the framework of the above points. For example, where to write a short solution or where to store open questions. Also “without a fixed place of residence” there were such moments as data flow diagrams and diagrams.


Extended version of the TOR according to the template

Let’s complete the tezeshka! Or rather, our miracle template. Several points need to be added. “Boar-boar and in production” – new TOR template is ready. It includes a few additional items:

  1. Table of contents – the table of contents is generated automatically, because we keep the formatting standard “Headings, subheadings, etc.”, you just need to leave this item in the template without touching it;

  2. Problem – taken out separately, so as not to be confused with the goal. Here we also briefly describe what problem we are solving;

  3. Solution – without technical details, we describe how we solve the problem and how we achieve our goal within the framework of this documentation, TOR, ChTZ;

  4. Open questions – floating block, which becomes smaller and smaller in the process of working through the document. Subsequently, he disappears altogether;

  5. backend. Versioning – you need to remember about the potential versioning of the business process if it is used by a mobile application;

  6. frontend. Scheme – a diagram of the data flow or interaction, if the scenario contains complex branching.

In total, the template grew fat up to 20 points.

Let’s go back to the beginning and try to answer the question, how much does 1 kg of TK weigh? It is not difficult to imagine how difficult and unbearable this method turned out to be. Moreover, the complexity of the work, no matter how absurd it may sound, is directly proportional to the simplicity of the task. The smaller the task, the more difficult it is to write a description of the development document (you need to go through the entire template, determine what is superfluous, remove what is not relevant, supplement empty items with the necessary information, or later you need to add what has already been deleted, etc. .). It became clear that more than 10 commands do not fit into one template.

A simple example on paws

Let me explain with cats how it looked from the outside, because everyone loves cats?

Meet the cat Petrushka and he is going to visit Vatrushka.

They are going to cook something delicious together. Let’s figure out what they need in order for them to get a cupcake. They need basic ingredients: butter, flour, eggs, sugar – four ingredients in total.

Vatrushka and Parsley go to the supermarket, but the store has only huge sets for making any kind of pastries. In the absence of other options, they take such a set with the idea that they will figure out on the spot which elements they will need from all this – the rest will have to be removed.

But, unfortunately, the cake was never made, and instead they sat and tried to figure out a large set of possible spices and flavors. It’s sad and sorry for the cats.

Here the thought was born: “What if the cats are given not a universal set for cooking, but only the ingredients they need? Let them choose what they need.”

And now let’s go back to the world of IT, banks and system analysis in general.


TOR for guidelines

It is necessary to reconsider the approach to the formation of documents – we make it as simple and convenient as possible.

Main idea – we provide the analyst with the opportunity to decide for himself what blocks the document will consist of. We go from the opposite: we do not remove unnecessary blocks, but assemble technical specifications from ready-made mini-pieces written according to the so-called guidelines.

In the terminology of system analysis, I have not yet met the concept of a guideline, so I will try to formulate it in my own words.

Guidelines are the rules that analysts follow when describing a single small block of a document. This is a list of step-by-step actions in order to completely form a separate part of the document. A separate guide is accompanied by examples (“fish”) for easier perception, as well as maintaining a single style of filling and formatting the document.

Whoop and done! A list of instructions of the decomposed TK template is formed. When writing the TK / CTZ itself, the system analyst understands which areas will be affected, and based on this, he himself forms a certain set of ready-made guidelines for the formation of the entire document.

The finished version of the instructions looks like this:

  1. [*] Block “Introduction and description” – table of contents with headings, table of local and cross-review participants, glossary, business goal, technical solution (briefly), open questions, link to UserStory;

  2. [*] Block “Business process diagram” – draw up a UML, BPMN diagram. A flowchart is also a valid way (it all depends on the level of the system analyst or business process);

  3. Block “Integration scheme” – interaction sequence diagram;

  4. Block “Revisions BE” – describe all the changes regarding the Backend:

    a) “Changes in API” block – endpoint name + method, service operation logic, enumeration of parameters, scopes and roles, data mapping, validation, specify response codes, etc.;

    b) Block “Changes in the database” – briefly describe why we create / change the table, describe the attributes, add an ER diagram, if necessary;

  5. Block “FE Changes” – we describe the scenario of the system behavior from the frontend, point out changes in the design, list the error handling;

  6. Block “Interaction with Bus” – scheme / sequence diagram of interaction, characteristics of the planned integration, attribute composition of integration;

  7. Block “Technical restrictions” – describe the technical limitations in the implementation and the reasons;

  8. Block “Testing” – give a recommendation on what criteria to select a test client, list auxiliary actions, focus on a negative scenario, describe the criteria for success, reflect information about a possible impact on existing functionality, reflect information about whether load testing is required;

  9. Block “Useful documentation” – leave any useful information on the task.

In total: we have reduced the volume of points from 20 to 9! At the same time, I want to draw attention to the process of creating a document – now it’s a set method, not an exception method. From the descriptions of each individual block, the final finished TOR is formed with the preservation of all formatting conditions, as a result of which the structure of the document is uniform and intuitive.

The cat comes to the store

collects the ingredients he needs,

the cat is happy!

Now, regardless of the size and complexity of the task, the document will be filled with only the necessary information and the time for maintaining the TOR will not be increased, as is the case with editing the template.


Let’s summarize once again what happened and what profit was formed from all of the above.

  1. The document is always created according to the same structure. Standard is our friend!

  2. The document contains only the necessary information without unnecessary noise and garbage. Cleanliness is the key to health!

  3. The time of work on TK has been greatly reduced due to the elimination of multiple edits and comparison of what is superfluous and what is not.

  4. TK on microservices! If we need to change the template or add new items, only separate independent processes are edited.

  5. Onboarding new specialists has once again become easier and connecting system analysts from other parallel teams does not cause difficulties.

  6. Petrushka and Vatrushka made a cake.

Profit! Yeah!

We are approaching the finale and I propose to finally weigh 1 kg TK according to the template and 1 kg TK according to guidelans. In one case, these are 20 fixed points, in the other – 9 variable blocks. So answer the question, what weighs more? 😉



Similar Posts

Leave a Reply Cancel reply