My name is Alexandra Kamzeeva, I have been working as a systems analyst for 9 years, of which 3.5 years at Lamoda. I read a lot, analyze the current documentation and create a new one. In my work, I always structure information and make it as convenient as possible.
The pros of a good system description are:
- helps you find the information you need faster and easier than in an unstructured description;
- reduces the risk of project failure;
- makes it easier for employees to onboard.
We made a template for such a description that any team can use. In this article, I will tell you with examples what prompted us to create a system description template, the history of its creation and how it is used now in Lamoda.
What is a template and why is it needed
First, I'll describe my understanding of the pattern. Let's pretend I need to find a small car in an untidy room. It's not a fact that I can handle it. But I can accidentally step on the Lego part.
Now imagine that all the toys are arranged in their places and sorted. I can see in advance which box all the cars are in, I will find the one I need faster, easier and I will not waste my nerves on it.
Likewise with the documentation. A template is such an order. We've made a framework for describing a system that any team can use.
In what conditions do we work with documentation
Lamoda has over 100 systems that automate order delivery, contact center, warehouse, photo studio, and other operational and business processes. More than 300 engineers are involved in development and support. Any of them may need a description of any of these 100 systems.
Each team independently describes their system in a separate space in Confluence. The technical lead is necessarily involved in the documentation, because he is obliged to record the information. Also, the system is described by active testers and developers who are sorry to just lose the knowledge they have gained. And, of course, analysts, since documentation is one of our main tools.
This freedom may seem to lead to chaos. But this is not so, because we have a company culture: a responsible attitude to documentation, open sharing of knowledge, the habit of recording project and system artifacts. This tradition has developed in part due to unsuccessful projects. The incidents proved to the development teams how important it is to document the processes and functionality of the system.
Below I will tell you a few cases when confusing documentation or lack of it led to problems.
Just add two buttons
The first problem that prompted us to create a template was that we did not have a description of some systems, which led to failures and improvements.
We had a Self Order Management (SOM) project. We decided to add two buttons to the client's personal account: "Transfer date of delivery" and "Cancel order". Prior to that, a client could only cancel or reschedule an order by calling the contact center. It is clear that some buyers did not have the time or desire to communicate with the operator. As a result, the sales representative could bring an unnecessary order or not find the client at home. In such cases, Lamoda bears the costs. The project was necessary and important.
It would seem to add two buttons! In fact, there was a lot of logic behind them in the four systems. Changing an order goes through the processing system - a huge monolith where you can touch something in one place and shoot in another. Unfortunately, the subtleties of her work were not described in the documentation, they did not pay attention to this during the design of the project. After the release, the buttons did not work as expected and it was rolled back. As a result, instead of two man-months, this project took six months.
Of course, we got this result not only due to the lack of documentation. But if we had a clear description of the processes of canceling and transferring an order, then perhaps the outcome would be different.
Complex onboarding
The second problem that led us to create a template is the complexity of onboarding. I came to work for the order processing system team. For immersion, I read the documentation in the system space and in three sections I found three different descriptions of the main essence of our system - the order status.
In this case, it didn't work out to make onboarding easier. Such documentation did not help transfer knowledge to colleagues who had not previously encountered our system.
Blank slate problem
The third prerequisite to template creation is the blank slate problem. For each new system, the tech lead must make the appropriate space from scratch. The Tech Lead thinks about which sections to create. Before creating the template, the employee studied other spaces and looked at which sections are used and will be useful for his system. This used to take a long time.
How we created the template and what happened
Every week, system analysts hold a stand-up and discuss issues that are encountered on projects and not only. And more than once colleagues have complained about how difficult it is to find information and understand the spaces of various systems. Since we constantly burned because of this, we decided to take into our own hands the description of the systems to which we are attached. And then it will be clear what to do.
First, we identified the attributes of a good template:
- .
- . , , . , . .
- . , , , .
- .
Next, we analyzed the current description of various systems and identified common sections:
In the section for projects and features, there were specifications for developing projects. The Development and QA sections contained specific information for development and testers. In the section of incidents, the incidents that occurred in the system and their solutions were described.
We shared the idea of a template with other colleagues at informal meetings (lunches in the kitchen, stand-ups, neighboring teams with whom you periodically talk) and created a working group of volunteers. They were representatives of different competencies: two managers, three technical leads and two testers. They added the following sections to the template:
Next, we tested the system description template with colleagues with broad competence: heads of IT departments, experienced tech leads and test leads of large integration projects. They ended up adding some more useful sections:
Checking the quality of the template
We checked the resulting document against our definition of a good template in Lamoda:
- It helps you find the information you need faster and easier. We have a convenient structure: I move along the tree and understand what is located and where. If you need information about the processes of the system (for example, canceling an order), then I go to “Description of the main processes”.
- System information is not duplicated due to the atomicity of the partitions. For example, you can describe printables in one section, and then link to it from the “Description of the main processes” section so that the information does not repeat itself.
- . Lamoda, . , -. — .
- . .
We made a nice template to describe Lamoda systems. I hope other companies will find it useful as well. I especially want to highlight the following three sections:
Description of the main processes of the system . Yes, it seems obvious that this section is needed. But for some reason it does not always exist, as was the case with us with the buttons for canceling and transferring an order. If we had described the cancellation and reschedule processes in advance, the risk of project failure would be reduced.
Checklists- a section that reminds of the most important in the regular process. For example, we have a “Checklist for connecting a new payment method” in the description of the payment methods management system. It says that we must coordinate the addition or change of a payment method with the accounting department, with the contact center, with delivery and with other business units.
Once we forgot to inform the contact center about the change in the payment method. And when the client called our contact center and asked about it, the operator could not say anything. This led to a conflict between the contact center and the development team responsible for payment methods. After this incident, we create checklists for key project launches, connecting new partners, etc.
Space home page- a section with information about why this system is needed, about the composition of the team and the stakeholder. We must coordinate system changes and development resources with the stakeholder. So it's great when you can get this information just by looking at Confluence.
Right there we indicate information about the composition of the team in order to understand who to contact with questions about the system. It also helps beginners with a swollen head. It's great when a new employee can spy on who he just talked to, who this person is, what his role is and what his name is.
How I got started using the template on my system
- First of all, I created the required sections of the template without filling. It was easy and took no more than 30 minutes.
- Then the most difficult thing was: we set up regular meetings with the tech lead, at which we began to analyze the documentation of our system. At the first meeting, we divided the current pages into three piles.
We have sent everything irrelevant and unnecessary to the first pile. We deleted these pages or sent them to the archive.
The second pile is necessary, but irrelevant. We marked the pages as irrelevant, created a task in Jira and then updated this information in accordance with our backlog.
The third pile is the simplest. When everything is clear, the sections are relevant - we just moved them to the right place.
Before these meetings, descriptions of processes and architecture, notes from testers and developers, and incidents were scattered throughout the space. There was also no home page.
For 6 hours of meetings, we got an excellent result. From chaos, we have formed structure and order. Now you can understand where to find the description of processes, information about the architecture and about incidents. And importantly, we now have a home page. Here it was written why an order processing system is needed and who is its stakeholder.
Our large system is involved in almost all business lines. But we didn't have our own stakeholder before. While we were doing the home page, we discussed with the CTO with whom to coordinate system changes. Thus, a colleague was determined, who prioritized the improvements. Now it looks like a fun fact that the creation of the home page led to the emergence of a stakeholder.
How We Distributed the Template
Similar results on the use of the template were received by other analysts who implemented it in their own directions. Thus, we have covered most of the systems that have been actively involved in many integration projects.
We had teams whose systems were often involved in integration projects, but there was not enough description about them. There usually was a need for documentation, so there was no need to sell the idea.
We have shown successful experience in applying templates to tech leads and managers of such teams. Some teams, based on our example, tidied up their documentation on their own, others asked analysts for help.
Feedback about the template
Our template is not a mandatory or mandatory system description. Colleagues take the template as a basis, if they have a need for it, and edit it to suit their needs. For example, they transfer exchanges from subsection to section if the system mainly consists of them.
All our systems are different in description, but the general structure and general logic are still preserved. Now we can more easily find information about what processes the system consists of, about the architecture of the system, and so on.
At Lamoda we love to share knowledge. We have large integration projects that motivate this. We send links to up-to-date descriptions of systems, and colleagues receive the necessary information without additional questions to already loaded tech leads.
2 years after creating the template, I interviewed colleagues and received good feedback from the majority. They use the template, editing the structure as they like.
But there are also people who think that we don't need documentation and a template. Basically, this is the reasoning of the teams of those systems in which there is now no urgent need to document something.
They work on systems that hardly change: there are no integration projects, there is no need to tell other colleagues about these systems, and accordingly, there is no desire to document.
I think that before starting a big project, our culture and the big bumps will remind you to document the main processes, and they will change their minds.
Advice to yourself and those who want to repeat our path
- , , , , . , .
- . , . , .
- , , . : , , . . , .