You can write flawless technical specifications, but what good is it if your developer is crying?

A spherical product owner is working in a galaxy far, far away. He writes notes fluently on a napkin and silently gives it to the developers. And soon he receives a finished product that 100% meets his expectations. Even if this product is a complex cross-platform service with blackjack and adaptability.



Is this possible in practice?



“No, brother, you can't fool us! The terms of reference should be written long and meticulously, ”say the gray-haired seniors. "TK is serious!" - the yellow-mouthed Juns echo them. “My wife left me because of a short technical assignment,” a seasoned business analyst admits.



Let me disagree.



Writing a TK does not have to be time consuming. Moreover, good terms of reference are easier to write than bad ones. If you know some tricks, of course. I'll tell you about this today. However, instead of napkins, I still recommend using confluence .

What's wrong?

I've been writing tasks for developers for over 11 years. Applications, games, web services, CRM systems, training platforms and other products were made based on them. During this time, I have gone from writing 200-page design docs to laconic terms of reference in several steps. And, of course, he filled all the possible bumps.



Year after year, in different companies, I watched how product, game designers, and marketers set tasks. And what are the consequences of the various "features" of the design of these tasks. How the start of the sprint is shifted by a week, figuring out what exactly the customer wants. As in a panic, they hotfix the functionality that has just been poured into the product. How quickly the app's rating drops due to unrecorded cases. How sales fall and loyal users leave. How developers burn out when they have to tinker with problematic tasks.



I got the impression that too many of those who set development tasks do not know how to do it well . And the question of the quality of TK itself is out of the focus of attention: they say, they wrote a task and norms, they won't figure it out, or what? Moreover, there are always more interesting things to do: discussing new hypotheses, meetings, coffee breaks. As a result, everyone suffers - customers, developers, and business.

There are two extremes when writing TK

The larger the product you are working on, the higher the cost of an error and the more important the quality of the technical specification (thanks, cap!). Therefore, both options are not suitable if you are doing something more serious than a landing page. In large and competitive products, writing TOR should be fast, smart, rock and roll . Let's see how to get there.

,

1. 
   
   – , , . , ( ).
2. 
   
   – , . , – , . .. , , . , – , .
3. PM-
   
   – , , . «», , .
4. QA
   
   – , . user journey . , , , .
5. The TK should please the team lead.
   
   This means that it does not require any special rituals and explanations to be transferred to development. For example, if a product has finished the technical assignment and he was hit by a bus right there, right in the office, this should not prevent him from making the technical assignment in the best possible way.

Is it difficult to meet all these requirements? Not at all.



On the contrary, if you remember about them, you will not be able to write frankly bad TK. Because all these requirements boil down to only one thing - taking care of the people who interact with this TK.

My TK format

This format is a fairly loose mixture of user story + definition of done .



It appeared as a result of many years of evolution: every time I saw a systematic problem, I changed the format of my TK so that this problem would not arise in the future. The result is a laconic and visually clean format that even junes can easily pick up. Plus, it meets the requirements described above.



Here's what a typical story looks like in my TK:







And no matter how large and complex the product we develop, any TK will consist of such simple stories (their number will only grow).





Important: stories should not describe too large functionality (for example, several screens) or too small (for example, one button). Typically, one story is one feature or product mechanic. For example, a story can fully describe the registration of a new user. To set a task for the layout of a new landing page, as a rule, one story is also enough for me.



If the technical specification is large and significant, then before the list of stories I briefly write: why we are doing it and what results we want to achieve . Just so developers have a big picture.

In general, it turns out something like this:

Example

Okay, to understand how this works - let's break a product into such stories. For example, we decided to make an application called "neural boot". In it, the neural network will conduct intimate conversations with products who have not had a day (and have no friends).



For simplicity, we assume that we already have a trained neural network and we need to make an interface for it in the form of an application.



Probably, the TK will consist of the following lines:

1. User authorization
2. User profile
3. Screen of communication with the neuroboot
4. Screen "Neuroboot catalog"
5. Profile and settings screen
6. Payment popup
7. Analytics connection

It remains to paint each story (in the above format) and send it to development. I told you it would be easy.

---

Tricky life hacks

There are a number of techniques that help me work on a product every day. Here are those that relate to writing terms of reference.

Life hack # 1: Detail iteratively

Now I do not write technical specifications at all - they themselves, in the background, appear in the process of work. When a new task appears, I immediately figure out: what subtasks are needed to do this? And then I fix each subtask in the story format (only the name, details will come later).



Thus, I immediately have a generalized terms of reference ready. It remains only to detail the story to the extent that it will be possible to give the technical assignment for development.



Detailing also goes in the background: while I'm researching and thinking over the details, I immediately make notes inside the corresponding lines. Instead of design, I insert prototypes from NinjaMock .



This approach significantly speeds up the work. Plus, it allows you not to miss the big picture and not dig into the details ahead of time.

Life hack # 2: Not working with genies

There was such an old movie where the genie made wishes come true in the worst possible way.



Of course, a sane developer will not specifically look for an opportunity to harm. But sometimes people don't care what they're working on. Then they do the task "as written", not really delving into why it is needed. Periodically this will result in large and small files. Well, yes, the production lay down ... but no one prescribed in the task what needs to be checked - whether such an implementation would break everything else.



I will not say about outsourcing, but this approach is not acceptable in the product. A good developer is building a temple, not just laying bricks. That is, he sees the big picture and delves into what is happening. Such guys often offer alternative solutions and warn about pitfalls themselves.



Therefore, if you want your TK to be done in the best possible way, then sometimes you need to improve not TK, but the development culture in the team. In general, this is a PM's task, but the product can also influence the situation. Especially if the team trusts him (thanks to his thoughtful and well-designed technical specifications, for example).

Lifehack # 3: Separate TK from documentation

The terms of reference answers the question "what needs to be done?" And the documentation - to the question "how is it done / how does it work?" TK is written before the implementation of the task, and the documentation is written after.



If I need to rearrange the cabinet, I will write a task in the spirit of “rearrange from here -> here”. But I will not draw the architectural plan of the house in which there is a wardrobe.



Sometimes there is an opinion that TK should be written so that it would be , as it were, at the same time, and documentation . This is a pernicious theory. Full documentation will still not work, because it is not known in advance how exactly the terms of reference will be implemented. In addition, developers need room to maneuver, which the documentation does not provide. And the main thing is to write such a TK many times longer and it will turn out to be cumbersome.



There are different products and different startups. Someone can do without documentation at all. But if you still need documentation, hire a june who will describe the functionality in detail after its implementation. You do not need special skills to describe the existing functionality, but you will save time and nerves for skillful employees - product developers and developers.

Life hack # 4: Learn to program

A purely empirical observation: Products that know how to program are better at formulating tasks. Moreover, it is not necessary to become a senior backend operator, it is enough to master any programming language and understand the essence of algorithmic thinking.



At one time I was still coding uncontrollably on the chthonic Spectrum , and in my student years I even had to write drivers in Assembler. That is, I am familiar with programming firsthand - and this, of course, helps to find a common language with developers.

Life hack # 5: Thinking a lot, writing a little

The biggest problems always arise with tasks that the customer himself does not fully understand. For example, he needs a new report in the admin area, but he does not quite understand how this report will be formed. Like, you programmers will figure it out. No, it doesn't work that way.



The only way to write a good problem that gets done right is to understand. Ideally, understand the problem enough that you could do it yourself ... if you knew how to program.



But when you figured it out - you don't need to dump all the information found in the TK. It is just a deep understanding of the task that allows you to discard unnecessary things and write only what matters.

---

PS TK is a means, not an end. Therefore, sometimes the best TK is its absence. Someday I'll tell you how I launched a couple of products without any technical specification at all.



PPS If you have your own format of terms of reference or life hacks when writing them - please share in the comments.