How to make a simple technical task and not lose money and nerves

    Hi, Habr! I am addressing this article to myself more young and inexperienced, as well as to everyone who feels insecure about the approach to technical documentation. Although if she helps someone from the bison of the project business, I will be doubly pleased.

    There are many standards and specifications for drawing up TK , but if young studios try to meet them when developing a simple online store, they will not have time to implement a couple of projects, as they go bankrupt, digging into a bunch of incomprehensible documents.

    What was before

    We are a small regional web development company, which, like many others, took up projects at the very beginning, without really knowing how to do them. But such a “forced growth” had an extremely positive effect on the team members, thanks to the great desire to develop, and helped to pump both skills and head. The development was getting better, but the terms of reference remained the lowest. Like most novice studios, we used the usual descriptive approach to TK: which pages, what should be displayed, some technical points, and everything, perhaps.

    On many projects this resulted in the following problems:

    1. Appearance is described, but not the principle of operation. A simple example with a basket online store. In the statement of work was written “Button“ Checkout ”. But what should happen when a user clicks this button? What are the rules for the order number? What status is assigned to it? Where does the redirection go? And if one of the goods was bought, while the user made out the order? There were no answers to these and many other questions in the TZ, and this is only one small element. Such unwritten moments led to disputes with the Customer, a strong exit from the budget and other unpleasant consequences.
    2. Lack of reusable blocks. Many sites have the same blocks used in different places, such as product previews. But this block as a result was described in each page. This is very bad for several reasons. Firstly, if necessary, changes must be made in several places at once, something may be missed and there will be a mismatch. Secondly, even with the same elements in the preview, the customer may require to make them differently, which entails additional costs.
    3. TK does not correlate with tasks for the team. The further the formulation of the problem from reality, the lower the quality will be at the output. This is another problem that I wanted to solve.

    New approach

    Having defined our goals, we developed a new, rather simple, but effective concept.

    TK consists of the following sections:

    1. Introduction
    2. Statics
    3. Dynamics
    4. Tasks
    5. Administrative panel
    6. General technical requirements

    From project to project, the composition of these sections may vary, but the basic structure remains. Let's take a closer look.

    Introduction and preparation for implementation

    • We briefly describe the project, its goals, Central Asia, leaving references to pre-project analytics.
    • We describe the project initialization process: setting up the environment for developers and the approach to developing a design concept for designers.
    • Principles of adaptability or versioning. Last time in our work we adhere to the following principle - “adaptive, everything that adapts”. In other words, at the beginning of work on the TZ, we understand what complex functionality we need (or may need in the near future) and together with the designer and front-end developer, we come up with ways to adapt it. With the new approach, there were still no negative results, so individual versions were not to be described.

    This section aims to bring the team up to date and prepare the ground for the direct development of the project.


    As we all know, pages can contain either static information or dynamic information sent from the server. Subsections static - project page. We divide each page into blocks. If the block is static, then we describe its essence and type of content. For example, a description of one of the blocks of the “About the Company” page might look like this. “The main advantages of the company. 5-6 icons with descriptions. ”This is a very brief but sufficient description of the block for an accurate assessment. When describing statics, the main goal is to set a clear framework. Adapting icons is not difficult, but with a graph or table everything is not so simple and straightforward. But at the same time, it doesn’t matter to us exactly which icons and captions to them.

    If the page contains a block that can be “braced out”, then at the place of its integration we write “The functional“ NAME ”is ​​integrated, and the functionality itself is described in the“ Dynamics ”section.

    In addition to the Static pages includes a description of the pop-up and letters. In my opinion, it makes no sense to place them in a separate large section and inflate the structure.


    Everything that relates to dynamics we call functional. Perhaps some sort of separation will appear later, since now different types of tasks belong here:

    1. Block. In the dynamics we make:
      • Blocks used in different parts of the site.
      • Blocks that it makes sense to evaluate separately. Firstly, it simplifies both the evaluation process itself and the customer’s understanding of the complexity of an individual element. Secondly, this category often includes blocks that are not vital for the project, and with this approach it is easier to exclude them from the budget.
      • Processes occurring at a specific user action. First of all, this includes actions that occur when placing an order, paying for it, adding it to the cart and so on. A similar functionality during the development of the project is often being finalized, and so these improvements are much more convenient to describe.
      • Integration of third-party services. Depending on the complexity of the integration, it can be described as one functional, or vice versa divided into many different ones to describe individual queries.


    This section is used for works that cannot be assigned to any of the other sections: draw a banner, set a metric counter, parse goods, etc.

    Administrative panel

    Here we describe the structure, models and fields. The splitting goes into sections, for example, “Goods”, “Catalog”, “Orders”, etc. We describe that different user roles can see what to edit.

    General technical requirements

    It includes quite a lot of subsections, not all of which are technical requirements, but again it did not make sense to make them separately:

    1. SEO requirements for tags and micromarking
    2. Transliteration Rules
    3. Manual and automatic testing
    4. Supported browsers
    5. ...

    New versions

    When describing new versions, it is necessary to make changes to existing elements. We considered the following ways of describing improvements: at the beginning of each section (Static, Dynamics, AP) write “Revision of the“ NAME ”functional, or make a separate section“ Revision ”, in which all the changing tasks will be dumped at once. So far we have settled on the second version, but this is connected more likely by convenience on specific projects. In other conditions, the first method is better.

    After writing the specification for the new version, we merge them into one so that the following can be written on the basis of one document.


    Let us, for clarity, analyze the structure of TK on the basis of a simplified page of the catalog section.


    Page “Directory Section”

    Used to display products belonging to a section of a directory of any level other than the root.

    The following functionality is integrated:

    1. “Bread Crumbs”
    2. “Directory tree”
    3. "Filtration. General provisions
    4. "Filtration. Text"
    5. "Filtration. Text and Image ”
    6. "Filtration. Range"
    7. "Sorting. Default"
    8. "Sorting. Ascending price “
    9. "Sorting. Descending price ”
    10. “Product preview. Tile"
    11. "Pagination. Page by page
    12. “Text block”. Integrated as a block for SEO-text in front of the basement of the site

    URL: / c / 1745-name, where 1745 is the id of the current directory category, and name is the transliterated name of this category.


    Since the page contains a lot of integrations, I will give examples for the two most interesting of them.

    Functional “Filtering. General provisions ”

    Externally, filtering is a series (or several rows) of buttons with the name of a filter. Clicking on the button opens a drop-down list with check-boxes with filter values ​​(values ​​of the corresponding characteristics of the product). The width of the drop-down list depends on the maximum length of the value in this list. In the visible area of ​​the drop-down list displays no more than 10 points. If the filter values ​​are greater, a scroll bar appears. Under the filter values ​​is the Apply button. If at least one value is selected and the user clicks the Apply button, outside the filter area or the button with the filter name, then:

    • the drop-down list closes, and the filter is applied. Only products that match the current active filters are left in the current section.
    • the name of the filter button takes the form: “Filter name: K”, where K is the number of selected filter values, if there are 2 or more, or “Filter name: value”, if one value was chosen.
    • the color of the filter button changes to the type of filter used
    • in the values ​​of other filters, only options remain that satisfy the current active filters. If one value in one of the inactive filters remains, its button becomes inactive, and the name is displayed in the format “Filter Name: Value”
    • For all active filters, a cross is added after the name; when clicked, only this filter is reset.
    • pagination is reset

    If at least one filter is active, after all the buttons with filters, the “reset filters” button appears, when clicked, the values ​​of all filters are reset.

    When switching from the current category to any other one, a check is made that the active filters and the values ​​selected in them are checked with the corresponding filters and the values ​​of the category to which the transition was made. In the newly selected category, those filters remain active and the values ​​selected in them that match.

    Filtering can be integrated in 2 ways: dynamically and statically. Dynamic integration allows you to set the characteristic by which filtering is carried out in the administrative panel. Such integrations are indicated without additional parameters. Static integration is applied to the default page. When describing the integration, an additional parameter is indicated - the characteristic by which filtering is performed.

    Selected filters are added to the URL via query parameters.

    Functional “Product Preview. Tile ”

    It is a tile (rectangle) with the most important information for the user about the product. In the version of the tile key information is the image of the goods. Preview contains:

    1. Price (integer in Russian rubles)
    2. Product Name
    3. Label “In store” or “From shop window”
    4. Picture
    5. The size
    6. Button “Add to cart” (Integration of the functionality “Add to cart”)
    7. Button “To favorites” (Integration of the functionality “Add to Favorites”)

    When you click on any area of ​​the preview, except for the “Add to cart” button, you are taken to the product page.

    On one line should be placed 3-4 tiles with a preview of the goods.

    As you can see, another is integrated into this functionality, which allows you to make very convenient partitions. For example, “Add to Cart” and “Add to Favorites” are also used in the item map.

    Administrative panel

    One page requires a large number of sections of the AP, I will describe one of them.


    List of all products with filtering. When editing / adding a product, the following fields are available:

    1. Title (text)
    2. Brand (radio)
    3. Images
    4. Price (integer)
    5. Description (text block)
    6. Type (store / showcase, radio)
    7. Condition. Meaning includes Title (text) and Explanation (text).
    8. Status. Possible options:
      1. on sale
      2. Moderation
      3. on completion
      4. rejected
      5. sold out
      6. failed check
      7. canceled by seller
    9. Tag size (optional). Text field without validation
    10. ...

    There are more than 30 fields and, in order not to inflate the article, we omit them.


    Pluses of the new approach:

    1. Completeness . This TZ allows you to uniquely describe the requirements, which is the main and necessary parameter of any TZ.
    2. Understandable . About half of our customers do not have a technical specialist on their side and face development for the first time. Therefore, it was very important to make TZ as understandable and readable as possible. And we did it! Even technically not savvy clients understand how it works, they can easily read it and give excellent feedback.
    3. Molecularity . The TOR fully complies with our requirements for splitting into separate elements, which greatly simplifies and solves the problems described above. TK blocks directly correspond to the tasks that are performed by the developers, which was met with a bang. Also, TK is a great fit for the design system (an article about it will be released next week).
    4. Easy assessment and configuration estimates . Well-described and broken tasks became easy and pleasant to evaluate. If during the assessment we understand that the requirements are incomplete, then we add them. For each project (stage) we make a Google table in which the customer can try different configurations of the project and determine the most suitable option for himself at a price / functionality.
    5. Interaction with customers has risen to a new level . The changes made allow you to clearly define the boundaries of the project. If changes need to be made with respect to TK, this is assessed as a new task, although with the old approach this caused a lot of controversy.
    6. Profitability . Because This is primarily a business, this indicator along with the previous one is one of the most important. Detailed study allowed to reduce the number of poorly evaluated tasks to a minimum. None of the projects implemented under the new approach did not exceed the budget.


    1. Making improvements . On one of the projects it was necessary to enter the statuses of goods. The result was a huge number of improvements to 2-3 lines. It can not be called a clear minus, because full requirements in priority, but the ideal data approach can not be called.
    2. The complexity of perception in the automation of business processes . If you take the business processes of some companies from the moment of sale to the receipt of the goods by the buyer, it is not always possible (or necessary at the first stages) to cover the whole process at the expense of Statics, Dynamics and AP, since many tasks are performed manually, are discussed with customers by phone, etc. This slightly complicates the perception of TK in its pure form, and requires additional description of the processes.
    3. Cost and development time . Of course, it became more difficult to sell TZ, because not everyone is ready to pay 10-20% of the project for the first contact with the development, while many of our competitors charge 10-20 thousand for it. project risks and improving quality.

    The advantages of the new approach have had a very positive effect on all aspects of our work and helped to identify weak points that were not previously paid attention to. Though there are minuses, but insignificant, especially in comparison with pluses.
    Each project brings something new, grinds corners and allows you to change it for the better.

    We are so pleased with the result that we decided to abandon the standard tasktrackers in favor of fine-tuning Google Docs for full-fledged work with TK-based tasks. If the experience is successful, we will write a separate article about it. In the meantime, we expect objective criticism and advice from you, with the hope that this article has helped someone).

    Also popular now: