Three months of errors, or how I created a checklist for checking technical specifications

Hello! My name is Nastya, I am a system analyst at X5 Tech. In this article, I want to share my experience of creating a checklist for a technical task (hereinafter referred to as TOR), what mistakes I made at the initial stages of working on a product, and how the generated checklist has helped me for three years now. Such a checklist can be useful not only for independent work on the TOR, but also as a tool for checking an already prepared document.

The article will be useful, it seems to me, to system and business analysts, product owners and those who work with requirements development.

background

Several online sources tell us that the first time the checklist was invented was in aviation (description can be read here or here). In short, in 1934, during the testing of a new Boeing model, a crash occurred: a fairly experienced pilot made a mistake. It was this case that showed that it is difficult for a person, albeit a trained one, to keep a lot of information in his head. So a certain list was invented, including the most important list of control and flight preparation processes. Such a list helped technical specialists in aviation, and over time was modernized, and even passed into the daily life of many people.

Checklists in the modern world

Every day we perform different tasks: some of them are automatic, others require a little more time and focus. But all of them somehow consist of a list of actions, which we call a checklist. Take, for example, various cleaning marathons (spring cleaning in three days) or an elementary shopping list – why not a checklist? Or a list of what you need to take on a trip. Not one of my trips is complete without such a checklist. Plus, the modern world has modern solutions: there are even books on writing checklists and a checklist for digital cleaning.

So why do we use them? To simplify and structure. Now there is a lot of informational noise, affairs and tasks around us, and it is easy to miss something important. Most of the time, our lists aren’t that complex, and forgetfulness doesn’t lead to plane crashes. However, the benefits of checklists are hard to deny, because they:

• reduce errors in our actions;

• save time on tasks;

• help not to think about the routine (we are talking about a special case, for example, going to the store).

Mistakes: failure or experience?

“Take advantage of every mistake.”

Ludwig Wittgenstein

As an analyst, I tend to simplify not only the work of programmers or customers, but also my own. In the first months of work at X5 Tech, I came across a large amount of information:

• variety of business processes in Pyaterochka stores;

• composition and configuration of the internal store system;

• several related divisions and development teams.

It became interesting for me to understand the processes, communicate with different people, collect and identify requirements. But keeping all the data in your head is difficult, memory began to fail, and developers and testers began to notice shortcomings in the technical specifications more often.

As a result, three months later, in order to improve the quality of development proposals (and, mainly, to reduce incoming questions from colleagues :)), I formed my own checklist of what needs to be taken into account in the TOR.

The first version looked like this:

How did I come to this? As cliche as it sounds, most of us learn from our mistakes, and our own. I will tell about them.

Mistake #1: Forgetting to describe what is frequently used

The information system that we are working on with the team is designed in such a way that the user sees his working documents with different statuses on different screen forms: a form with active documents (which you can still work with) and a form with archived documents (not available for changes) . So, the changes most often concerned the form of active documents – add a hint to the field, a new column in the table, a new field. And since the archival form often repeated the active one, the changes in it should be similar.

For example, consider the process of making a claim to the supplier regarding the quality of the goods. In this case, the store manager needs to perform the following actions:

• draw up an electronic act of disagreement;

• print the act;

• sign the act;

• send it to the Claims Department.

The approval of the act depends on whether it was issued in the first minutes of acceptance of the goods with the driver or within 24 hours already without the driver. Thus, the claims specialist needed to see the way the act was executed. But even if all the information is available in electronic form (here we are integrating between systems), a specialist and a director can exchange clarifying information with each other. And if the director needs to see how the act is displayed (in the electronic archive of documents), then, obviously, we should have added the display of this method in the archival act. What I “successfully” forgot to indicate in the TOR and what was not written in the business requirements …

It turned out that the user’s path ended at the stage of working with the active document and did not describe his actions with the archived one. The problem was discovered by the developer in one of the tasks, when he saw the link between the active and the archive form in the code. After conferring for three – me, a developer and a tester – we decided to finalize this moment in the current release and not transfer it to the next one. So the changes for the user looked more logical and did not raise questions regarding different interfaces of the same form.

Mistake #2: Forgetting to describe things that are rarely used

Not all tasks involve changes to the same functionality. For example, there may be changes only to screen forms and not affect changes to printed forms, or vice versa. The same applies to system configuration changes. It’s not often used in day to day development, but it could be part of a new feature. And without this part, the picture for the user, again, will be incomplete.

Sometimes testers, when checking a task, go through not only the revisions and alternative scenarios directly, but also test “about”. This means that functionality related to the user path that we are improving, but not included in the initial development scope, can be tested. So we found that in one of the tasks we lacked the refinement of the printed form. And since the changes were small, they made it to the already written TK.

Here is an example of a screen form with data on the display of goods on the shelf:

And this is what the form looks like:

It can be seen that the fields “Face Width / Face Height / Layout Style” are present both in the document for printing and on the screen form, but initially in the TOR I did not prescribe the addition of this data to the printed form.

Mistake #3: Forgetting to describe changes on all devices

If the system has desktop and mobile versions, then the changes should be both there and there. The teams involved in mobile development and desktop development are different. Analysts, testers, developers do not intersect among themselves in all improvements, and business requirements are more often formulated for the system in general.

The customer expects that the functionality will be implemented on all devices, but in fact it turned out that the release only supported changes in the desktop version. Development on mobile devices “moved” to the next release due to time and resource constraints that were not originally planned. Improvements were made in the following months, and in fact, for the user, the mobile version at that time became a stripped-down version of the desktop one. This backlog lasted for several release cycles, but in the end everything leveled out.

There were several more cases in which, one way or another, improvements in already agreed requirements surfaced.

How did we solve it?

• some errors were corrected at the time of coordination of the TOR and development;

• some through CR (Change Request – change request) after development, on the pilot of a new version of the system;

• some moved to the next release.

My checklist is my charm

All previous mistakes and decisions helped me to form my own checklist, which I use to validate TK. According to it, I check the document before giving it to development: did I take everything into account in the description? Are all alternative scenarios listed? Are all devices described, etc.

And, of course, I was very happy when it stopped filling. After all, this meant that most of the cones were already stuffed, which means that more complete and accurate technical specifications could be drawn up.

Formally, my checklist contains the following items:

You can download the summary checklist Here.

My list contains a review of highly focused business processes, for which our team is responsible for refining. And if the task is quite voluminous (business requirements imply revision for more than one sprint or release), then I will definitely check the TOR with this checklist.

After a year of work and to this day it looks like this:

I also want to add that if the project or area of ​​automated activity is complex (includes a lot of details or just a lot of information), then it is better to create your own checklist in advance. Try to form it purposefully, and not on mistakes. I hope this will be less painful for the team, and my checklist will help you with this.

Application of a checklist for TK

If we talk about the benefits of my checklist, then for myself I have identified three situations in which I use it:

1. when agreeing on business requirements: check whether the business analyst and the customer have taken everything into account;

2. when writing TK: easier to break down into tasks for development. For example, you can issue separate tasks for changing the database, changing screen forms, integration;

3. in the process of development: answers to questions from developers and testers – why is it so and not otherwise written in the TOR. And because, following the checklist:

   • coordinated changes with architects;

   • used corporate guidelines;

   • communicated and agreed requirements with business experts/customer on various business processes.

Why else might you need a checklist for TK?

going through such a checklist, I realized that sometimes in the finished TOR I forgot to indicate some requirements for development. And, thus, the checklist helped me to correct the situation in advance, when changes would have to be made already at the time of development.

sometimes functionality could be present on one form and absent on another intentionally, but thanks to the checklist, I knew that the customer needed such a difference in requirements, and not that he or I simply forgot to indicate this in development documents.