Recipe for the Perfect Analytical Article

Often, an analytical article becomes a point of confrontation between the analyst and the rest of the development team. Although their wishes for the article clearly do not contradict each other…

• Analyst: “I want to quickly develop documents that will only inspire admiration from those who are lucky enough to read them. Everything will be clear to everyone, and it will be done exactly as written.“

• All development team members: “We don’t want to read a huge, incomprehensible text, trying to extract the necessary information from it. Everything should be short, to the point, clear and unambiguous“.

There are no contradictions in these positions. But there are nuances that arise from the complexity of the subject of the article. This leads to several problems:

• large volume, the article becomes redundant;

• insufficiency of information, namely the lack of data necessary for certain team members (in this case, the same article can be both redundant and insufficient);

• navigation difficulties, when difficulties are caused by finding the necessary information.

All this leads to increased labor costs for any work related to the article, be it its development, reading, correction, checking, and so on).

Before getting into the IT industry, I worked as a design engineer at a mining and processing plant. Now I can say with confidence that the work of a design engineer in a small design department and the work of an IT analyst are fundamentally the same type of activity. The task of both the designer and the analyst is to describe WHAT needs to be done by those specialists who know HOW to do WHAT. But the designers’ problems have been solved thanks to the ESKD (Unified System of Design Documentation), which has been perfected over decades – it dictates how design documentation should be drawn up.

Of course, the situation is different for analysts:

• the subject area itself requires different approaches for different tasks;

• work in development teams is specific in its own way;

• The entire IT industry is characterized by a high rate of change.

Therefore, a rigid system similar to the ESKD will not be optimal.

In April 2024, at an internal conference of ASCON developers, I tried to get closer to solving the identified problem. For this purpose, a meetup was planned, the task of which I stated was to determine the requirements of the development team’s roles for analytics. All in order to assemble a template for an analytical article.

Of course, it was decided to approach the issue analytically:

• collectively identify people interested in analytical articles;

• determine stakeholder requirements for the analytical article;

• evaluate the most convenient tools and forms of presenting information.

Stakeholders

In fact, all team members interact with analytics at certain stages of their work, so we feel free to include everyone on the list, from programmers to technical writers. And even outside the development team there are stakeholders.

Gathering requirements

Next, using the User Story formula, I will formulate the stakeholder requirements for analytics.

1. I'm like programmer:

   1. I want the article to contain brief description of the subject area, for a general understanding of the problem solved by the functionality.

   2. I want the article to contain brief information about the connection between the new functionality and the existing one, in order to identify issues related to the architecture.

   3. I want the article to contain acceptance criteria for self-testing.

   4. I want the article to contain data on performance, convenience, fault tolerance, taking into account the purpose and limitations of functionality

   5. I want the article to be formatted into easy-to-read blocks for ease of working with it

   6. I want the article to contain detailed user scenarios (possibly with interface layouts), for a complete understanding of the functional block being developed

   1. I want user scenarios to be described based on complex scenarios (large number of users, parameters, data)

   7. I want the article to describe variable names that correspond to the subject area in order to avoid incorrect naming on the part of the programmer.

2. I'm like tester:

   1. I would like to see in the article a description of the user task solved by the functionality to understand the correspondence of the functionality to the original request

   2. I want to see a description of emergency situations in the article, for a complete understanding of the system’s actions in complex scenarios

   3. I want to see links to non-functional requirements.

3. I'm like analyst:

   1. I want the article to contain brief information about the connection between the new functionality and the existing one, for ease of finding information when developing analytics

4. I'm like development team leader:

   1. I want to see in the article a breakdown into blocks of work for planning

   2. I want to see in the article the prioritization of features for planning

   3. I want to see links to related tasks in Jira in the article for ease of navigation.

5. I'm like technical support specialist:

   1. I would like to see a section in the article containing a description of the differences between the implemented functionality and the original analytics, in order to obtain reliable information about the functionality.

6. I'm like marketer:

   1. I want to see a description of the original issues in the article for use in marketing materials

   2. if we are talking about a new product, then I want to see a separate article describing the concept of the product for use in marketing materials

   3. I want to see detailed user scenarios to select the most striking use cases for use in marketing materials

Sample

Table of contents
Structure of article sections

Links
To related documents/articles

Introduction
Description of the problem and preliminary description of the functionality

Requirements

Non-functional requirements
Block for describing non-functional requirements.

Custom Scripts
Precondition:…

Description of emergency situations
Description of the system's reaction to possible errors, etc.

Difference from actual implementation
Description of implementation nuances that do not correspond to analytics

Conclusion

Of course, the main positive result of the meetup was not the template. The most valuable thing was understanding the requests of colleagues that they make for an analytical article. This is exactly what is needed to make the article truly convenient and understandable for the entire development team.

For help in I thank my colleague Alexander Kondusov for writing the article.