Three Months of Mistakes, or How I Created a Checklist to Work on Design Specifications
Hello! My name is Anastasia and I am a system analyst at X5 Tech. In this article I’d like to share my experience in creating a checklist for working on design specifications or technical design assignments (TDA). I will discuss mistakes I used to make at the initial stages of working on a product, and how the checklist I created has been helping me for three years now. Such a checklist can be handy not only for independent work on design specifications, but also as a tool for checking the final, ready-made TDAs.
I believe this article will be useful to system and business analysts, product owners and those who work on the development requirements.
Backstory
According to various online sources, the concept of checklists was invented in aviation (you can read more here and here). In short, during the testing of a new Boeing model back in 1934, the pilot error led to a flight crash. It was this accident, which showed that it is difficult for a person, even a trained one, to keep lots of information in his head at one time. So, a checklist was invented, which included the most important flight control and flight preparation processes. At first, such lists helped technical specialists in aviation, and over time, they were upgraded and later became a commonplace in the daily life of many people.
Checklists in the Modern World
Every day we have different tasks at hand: some of them are performed reflexively, others require a little more time and focus. But, anyway, probably all these tasks consist of a list of activities, which we call a checklist. For instance, a plan of a cleaning marathon (when you have to perform the complete spring cleaning in just three days), or a simple shopping list — basically represent a checklist.
Or, imagine, you are getting ready for a trip, creating a list of items you want to take with you. I am drafting such checklists for all of my trips. Besides, the modern world offers modern solutions: there are even books on compiling checklists, and there are even checklists for digital cleaning.
So why do we use them? To make our life simpler and to structure our activities. Today there is a lot of informational noise around us, and we have to deal with a plenty of various tasks in our busy life, which makes it so easy to miss something important. Most of the time, our tasks aren’t that complex, and our absent-mindedness doesn’t lead to plane crashes. However, the benefits of checklists are hard to deny, since they:
- reduce the number of errors in our activities
- save us some time on performing tasks
- help us not to think about the routine work (we are talking about some certain scenarios, like, shopping).
Mistakes: fiasco 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 work. In the first months at X5 Tech, I had to deal with a huge amount of information:
- a variety of business processes in Pyaterochka stores,
- composition and configuration of the internal store system,
- several related departments and development teams.
I became keen to understand the processes, communicate with different people, collect and identify requirements. But it was difficult to keep all this data in your head, I started forgetting things, and developers and testers began to notice shortcomings in design specifications more often.
As a result, three months later, in order to improve the quality of development proposals (and, mainly, to reduce the number of questions from colleagues), I created my own checklist of what needs to be taken into account when working on design specifications.
The first version of this checklist looked like this:
So how did I come to this? As cliche as it may sound, most of us learn from mistakes, mainly from our own ones. So, let me talk about them.
Mistake #1: Forgetting to describe what is used most often
The information system that our team is working on is designed in such a way that users can view their working documents with different statuses on different screen forms: a form with active documents (which they can still work on) and a form with archived documents (not available for changes).
As a matter of fact, most often the changes were made to the form with active documents — we added hints to the fields, new columns to the table, or even new fields. Since the form with archived documents often repeated the form with active documents, the similar changes were to be made in the former one.
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 the act to the Claims Department for consideration.
The approval of the act depends on whether it was issued in the first minutes of acceptance of the goods in the presence of the driver, or within 24 hours (without the driver). Accordingly, the claims specialist needs to see the way the act was drawn up. But even with all this information being available in electronic form (we are integrating this process between our systems), the claim specialist and the store manager can exchange more detailed information with each other. And if the store manager needs to see the way the act is displayed (in the electronic archive), obviously, we should have added such functionality in the archived act. This is exactly what I managed to forget in the design specifications, and which was not specified in our business requirements…
So, the user’s journey ended up at the stage of working with active documents, not describing their actions with the archived documents. The problem was discovered by one of our developers, when he saw the relation between the ‘active’ and the ‘archive’ forms in the code.
After a small meetup — me, the developer and the tester — we decided to fix this moment in the current release, without moving it to the next one. With this fix, the changes for the end user looked more logical and did not raise questions why the same form had different interfaces.
Mistake #2: Forgetting to describe what is used rarely
It is not necessary that all our tasks require changes in functionality for the entire thing. Sometimes, there may be changes only to screen forms, without affecting printed forms, or vice versa. The same applies to system configuration changes. This might not be the case in our day-to-day development, but could easily be part of a new feature. And without this part, the picture for the end user, once again, will be incomplete.
Sometimes our testers, when reviewing a task, go not only through the revisions under consideration and alternative scenarios, but also test some ”adjacent areas”. This means that they can also review some other functionality related to the user journey, which we are improving, but which has not been included in the initial development scope. Once, during such a review, we found out that in one of the tasks we needed to make some updates to the printed form. And since the changes were small, we made it to the already created design assignment.
Here is an example of a screen form containing data on goods layout on the shelves:
And here is the corresponding printed form:
One can notice that the fields “Face Width / Face Height / Layout Style” are present both in the printed form and in the screen form, although initially I did not specify the addition of this data to the printed form in the technical design assignment.
Mistake #3: Forgetting to describe changes for all of the devices
If the system has a desktop and a mobile version, changes should be made both in the desktop and in the mobile version. The teams involved in mobile development and desktop development are different. Analysts, testers, developers do not necessarily keep in touch when working on improvements, and business requirements are more often formulated for the system in general.
Customers expected certain functionality to be implemented on all devices, but in fact it turned out that in the release, changes were made only to the desktop version. We had to postpone changes to the mobile devices to the next release, since they required time and resources that had not been planned initially. Improvements were made in the following months, and in fact, during that time users had to rely on a stripped-down version of the desktop application. This backlog lasted for several release cycles, but in the end, the versions got synchronized.
There were several other cases, when we had to make improvements and changes to the approved assignments.
How do we find the way out of such situations?
- Some mistakes are being corrected at the time of approval of the design specifications or consequent development.
- Some of them are rectified through change requests (CR) — after development, in the pilot runs of a new version of the system.
- Some are postponed to the next release.
My precious checklist
All the mistakes and decisions I made helped me create my own checklist, which I use to validate design specifications. Before sending specifications to the development team, I review their specifications through this checklist to make sure that I haven’t forgotten anything in the description, and that I have specified all the alternative scenarios and devices, etc.
Needless to say, I was very happy when my checklist stopped expanding. After all, this means that most of the possible mistakes have been already accounted for, which means that we can end up with better, even more complete and accurate technical specifications.
Technically, my checklist consists of the following items:
1. Items most often improved in each task
Example: changes in the database (fields format and dimensions), improvements in screen forms.
2. Rarely updated items
Example: reports, printed forms, field filters.
3. Items specific for business processes
Example: Different user journeys reaching the same target: improvements should be described for all such possible situations.
4. Different formats or devices
Example: desktop or mobile versions. Mobile versions with various interfaces for various physical devices (Android or Windows devices).
5. System configuration
Example: advanced deployment options, system settings.
6. Integration with other systems
Example: format and dimension of integration parameters between systems. Are all systems taken into account?
7. Checking the description of data formats or messages for compliance with accepted standards / development guidelines
Example: if there are corporate standards, then they must be met.
This checklist is available here.
My checklist is intended to review the highly specific business processes our team is responsible for. If the task at hand is quite large (and business requirements usually imply lots of revisions — for more than just one sprint or release), then I will definitely review design specifications through this checklist.
After a year of work and up to this day it still looks like this:
Besides that, if you are dealing with a complex project or automating quite a large scope of activities (that includes a lot of details or just a lot of information), it would be better to create your own checklist in advance. Try to build it purposefully, not on mistakes. I believe this will be less painful for the team, and my checklist will help you with this.
Using the checklist when working on design specifications
As for the benefits of a purpose-made checklist, I defined the following three scenarios, when it becomes handy:
- When agreeing on business requirements, it helps to check whether the business analyst and the customer have taken everything into account.
- When working on design specifications, it helps to decompose the problem into smaller development tasks. For example, you can define separate tasks for changing the database, changing screen forms, and integration.
- In the development phase, it helps to answer the questions from testers and developers. Why do design specifications define the task exactly in this way, not otherwise? Because, using the checklist:
- I coordinated the changes with the architects.
- I used the corporate guidelines.
- I communicated with business experts or the customer, discussing various processes and agreeing on the requirements.
Why else might you need a checklist when working on design specifications?
- Not to forget to do something:
Sometimes, looking through such a checklist, I realized that I forgot to indicate certain requirements for development in the finished design specifications. Thus, the checklist helped me correct the situation in advance, without having to make changes at the time of development.
- To avoid doing what is not needed:
Sometimes, a feature could be present in one display form, but deliberately removed from the other one. With this checklist, I can be sure that it was the customer who needed the different forms, and it was not just an oversight in the development specifications.
