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 project bison, I will be doubly pleased.
There are a lot of 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 in a bunch of incomprehensible documents.
We are a small regional company engaged in customized web development, which, like many others, took up projects at the very beginning, without really knowing how to do them. But such a “forced growth” had a very 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:
Having defined our goals, we developed a new, rather simple, but effective concept.
TK consists of the following sections:
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
This section aims to bring the team up to date and prepare the ground for the direct development of the project.
Statics
As we all know, pages can contain either static information or dynamic information sent from the server. Subsections statics - project pages. We divide each page into blocks. If the block is static, then we describe its essence and type of content. For example, the 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.
Dynamics
Everything that relates to the dynamics we call functional. Perhaps there will be some more separation later, since now different types of tasks belong here:
Tasks
This section is used for works that cannot be attributed to any of the other sections: draw a banner, set a metric counter, match items, etc.
Administrative panel
Here we describe the structure, model and field. The breakdown is divided into sections, for example, “Goods”, “Catalog”, “Orders”, etc. We describe that different user roles can view what to edit.
General technical requirements
It includes quite a lot of subsections, not all of which are really technical requirements, but again it did not make sense to make them separately:
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“ Refinements ”in which all the changing tasks will be dumped in a heap. 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 TK to 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 catalog section of any level other than the root.
Integrates the following functionality:
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
Outwardly, 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 larger, a scroll bar appears. Below 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:
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 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:
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 product map.
One page requires a large number of sections of the AP, I will describe one of them.
Product
List of all products with filtering. When editing / adding a product, the following fields are available:
There are more than 30 fields and, in order not to inflate the article, we omit them.
Pluses of the new approach:
Minuses:
The advantages of the new approach had a very positive effect on all aspects of our work and helped to identify weak points that had not been 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).
There are a lot of 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 in a bunch of incomprehensible documents.
What was before
We are a small regional company engaged in customized web development, which, like many others, took up projects at the very beginning, without really knowing how to do them. But such a “forced growth” had a very 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:
- 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 TK, 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.
- Lack of reusable blocks. Many sites have the same blocks used in different places, for example, 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 can 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.
- TK does not correlate with tasks for the team. The further the statement 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:
- Introduction
- Statics
- Dynamics
- Tasks
- Administrative panel
- 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.
Statics
As we all know, pages can contain either static information or dynamic information sent from the server. Subsections statics - project pages. We divide each page into blocks. If the block is static, then we describe its essence and type of content. For example, the 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.
Dynamics
Everything that relates to the dynamics we call functional. Perhaps there will be some more separation later, since now different types of tasks belong here:
- 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, conversely, split into many different ones to describe individual queries.
Tasks
This section is used for works that cannot be attributed to any of the other sections: draw a banner, set a metric counter, match items, etc.
Administrative panel
Here we describe the structure, model and field. The breakdown is divided into sections, for example, “Goods”, “Catalog”, “Orders”, etc. We describe that different user roles can view what to edit.
General technical requirements
It includes quite a lot of subsections, not all of which are really technical requirements, but again it did not make sense to make them separately:
- SEO requirements for tags and microdata
- Transliteration Rules
- Manual and automatic testing
- Supported browsers
- ...
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“ Refinements ”in which all the changing tasks will be dumped in a heap. 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 TK to the new version, we merge them into one, so that the following can be written on the basis of one document.
Example
Let us, for clarity, analyze the structure of TK on the basis of a simplified page of the catalog section.
Statics
Page “Directory Section”
Used to display products belonging to a catalog section of any level other than the root.
Integrates the following functionality:
- “Bread Crumbs”
- “Directory tree”
- "Filtration. General provisions
- "Filtration. Text"
- "Filtration. Text and Image ”
- "Filtration. Range"
- "Sorting. Default"
- "Sorting. Ascending price “
- "Sorting. Descending price ”
- “Product preview. Tile"
- "Pagination. Page by page
- “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.
Dynamics
Since the page contains a lot of integrations, I will give examples for the two most interesting of them.
Functional “Filtering. General provisions
Outwardly, 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 larger, a scroll bar appears. Below 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 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:
- Price (integer in Russian rubles)
- Product Name
- Label “In store” or “From shop window”
- Picture
- The size
- Button “Add to cart” (Integration of the functionality “Add to cart”)
- 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 product map.
Administrative panel
One page requires a large number of sections of the AP, I will describe one of them.
Product
List of all products with filtering. When editing / adding a product, the following fields are available:
- Title (text)
- Brand (radio)
- Images
- Price (integer)
- Description (text block)
- Type (store / showcase, radio)
- Condition. Meaning includes Title (text) and Explanation (text).
- Status. Possible options:
- on sale
- Moderation
- on completion
- rejected
- sold out
- failed check
- canceled by the seller
- Tag size (optional). Text field without validation
- ...
There are more than 30 fields and, in order not to inflate the article, we omit them.
findings
Pluses of the new approach:
- Completeness . This TZ allows you to uniquely describe the requirements, which is the main and necessary parameter of any TZ.
- Comprehensibility About half of our clients 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 customers understand how it works, they can easily read it and give excellent feedback.
- Molecularity TK fully meets our requirements for splitting into separate elements, which greatly simplifies and solves the problems described above. TK blocks directly correspond to the tasks 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).
- Easy estimates 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.
- Interaction with customers has risen to a new level . The changes make it possible to clearly define the boundaries of the project. If it is necessary to make changes regarding the TK, this is assessed as a new task, although with the old approach it caused a lot of controversy.
- Profitability . Since 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.
Minuses:
- 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 an obvious minus, because full requirements in priority, but the ideal data approach can not be called.
- 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 PA, 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.
- Cost and development time . Of course, selling TK has become more difficult, because not everyone is ready to pay 10-20% of the project for the first contact with the project, while many of our competitors charge 10-20 thousand for it. But this kind of work pays for itself in the implementation project risks and improving quality.
The advantages of the new approach had a very positive effect on all aspects of our work and helped to identify weak points that had not been 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).
Source: https://habr.com/ru/post/418199/
All Articles