Design solutions: playing by your rules

It is no secret that the larger the software project, the more its success depends on the results of the analysts' work, in particular, on the choice of the correct strategy for drawing up and agreeing design decisions. However, how do you organize the work of these creative collaborators? And how to make the results of their activities equally clear to both the customer's representatives and the programmers? How to assess the possible time frame and the significance of this work for the project? In this article, I tried to formulate my recipes for optimizing the management of analytical work on software projects for government customers. Any criticism is appreciated.



A source

Research framework

, .



.

Since at the moment there are more than two dozen types of “analyst” vacancies on the IT labor market , I will immediately make a reservation that I will talk about analytical work on state projects to create custom software. As my experience shows, a business analyst who does not understand the mechanisms for automating business processes cannot prepare an adequate statement of the problem. Just as a systems analyst who does not understand the business goals of automation cannot be adequate. Therefore, from my point of view, an analyst working on custom software projects should combine the competencies of a business analyst, systems analyst, and UX designer. In addition, as a rule, the lead analyst on such a project must perform the functions of the Product Owner.(if the customer allows you). It is about the organization of the activities of such "universal soldiers" that will be discussed further.



When creating software in the interests of government organizations, the main activity of analysts is associated with solving such problems as:

• requirements management;
• formation of task statements for programmers, implementation planning and control over the implementation of these tasks;
• preparation of project documentation.

The details of managing the requirements for custom software, the procedure for their initial refinement and the key role of the analyst responsible for their implementation were discussed in detail in the previous article .



However, the specificity of the customer's wishes is not a guarantee that he will like the final result. In the course of my projects , the following pattern was "identified": all the functional comments of the customer, recorded during all types of tests (not to be confused with the identified errors!), Related to requirements for which the design solution was not proactively agreed with the customer. In this respect, the statistics given by Natalya Rukol are indicative.when, when analyzing the results of one of the projects, it turned out that almost 70% of the "errors" revealed at the stage of delivery were caused by a lack of understanding of the initial requirements on the part of the developers. 



It would seem that after the requirements for the software product have been clarified, it is necessary to form a package of design documentation in accordance with GOST RD 50-34.698 , coordinate it with the customer and then develop software in full accordance with the approved project. It is often about this sequence of actions that one hears from yesterday's excellent students (C grade students, as a rule, do not know about the existence of such documents at all) and many "experienced" top officials who have never been personally responsible for the final result of software development. 



As my experience suggests, the formation of project documentation is only the final part of the analyst's work. As an analogy, one can cite a research work, as a result of which a report should be generated in accordance with GOST 7.32 or a dissertation should be written. However, these documents are just a form of formalizing the scientific results obtained. Conducting fruitless experiments, statistical processing of "white noise", searching for grains of the required information in tons of pseudoscientific waste paper - all these integral parts of scientific work always remain behind the scenes. The same is the case with project documentation. On the one hand, it is an integral part of the software product... On the other hand, it contains only the final results of the analytical work.  





Source



In my opinion, this aspect is one of a number of reasons why, according to the requirements of government contracts for software projects, “stupid” customers plan to agree on the design documentation at the stage of preliminary testing, i.e. at the time of actual completion of software development.



That is why, in our software projects in JIRA, two different types of tasks are formed, which allow us to separate the analytical work directly from the activity of preparing the project documentation. And what is gratifying, I was not the only one who came to such conclusions... So what exactly should analysts do on a software project after specifying the requirements and before drawing up the project documentation?

Design solutions VS design documentation?

How beautiful it is on paper,

How easy it is to follow words.

How easy it is to make you infallible.



B. Grebenshchikov

Despite the fact that the definition of the concept "design solution" is given in GOST 34.003-90 , in my case the meaning of this concept was "discovered" in the course of painful and fruitless attempts to agree with the customer representatives of several interrelated but ambiguous requirements, when the clients simply ignored the proposed we describe the setting of objectives ( TMP ), formed in strict accordance with RD 50-34.698-90. After realizing that the decision on the part of the customer would not be made until the start of testing, the following maneuver was undertaken: our design solution was sent to the customer (i.e. a solution that he was not formally obliged to agree on). 



The ritual attributes were retained in the design solution, but significant adjustments were made to this document compared to the hosted HMO. The design solution was supplemented with a diagram of an automated business process with a brief description, user interface layouts, forms of received reports for printing, proposals for the distribution of access, as well as a short scenario for the delivery of this design solution. In terms of ambiguous and conflicting requirements, an unambiguous and detailed description was made. However, the rest of the text was minimized in every possible way. Trivial algorithms were not described at all, just as fields of screen forms were not described, the purpose and validation rules of which were clear from the given UI layouts.  



The resulting cocktail was at the same time similar in shape to a document drawn up in accordance with the requirements of RD 50-34.698-90, but in fact it did not correspond to any of the formats given in this GOST. At the same time, what was written in it was understood by an ordinary, unprepared representative of the customer. The requirements specified in this document were perfectly clear for both the customer and the contractor. The boundaries of the requirements, the required scope of the planned work and how these works should have been completed were determined.



The cover letter contained something like this:



“We present a variant of a design solution to meet the listed requirements. We inform you about the beginning of work on the implementation of the presented option. If you disagree with the proposed design solution, please inform us about it. "



In case of further discussion of the requirements, the absence of a response to such a letter was interpreted as a formal agreement of the customer with the proposed design solution. If the customer sent objections, in this case he was informed that the work on the implementation of this design solution was suspended and could not be continued until its approval. In this case, as a rule, further approval went much faster.



What is funny, at first in reply letters if the customer did not send the necessary clarifications, we used the phrase "work is suspended." After several such letters, one of the customer's representatives created a scandal in connection with the fact that "according to the signed contract, we cannot suspend work and the lack of clarification regarding the requirements is not a reason for terminating development." However, he had no objections to the statement that "the work cannot be continued". 



As it turned out later, despite the fact that the formed structure of the design solution did not meet the requirements of GOST, the proposed approach greatly facilitated the ritual body movements for the formation and approval of design documentation. The content of the design documentation, which was required for the delivery of the project, was formed by selective copying of the relevant sections of design solutions. At the same time, in relation to the sections of the documentation that were formed on the basis of preventively "agreed" design decisions, no comments were made by the customer during the acceptance.

 Description of the elephant not according to GOST

The truth is, customers don't know what they want. Usually they do not know what questions need to be answered, and almost never thought about the problem in such detail as it should be indicated in the specification. 



Frederick Brooks

In my opinion, the main criterion for a good description of the problem statement (design solution) is not the fulfillment of the formal requirements of GOST, but an unambiguous description of the conditions for the successful completion of work on meeting the customer's requirements. From this point of view, the description of test items for checking requirements is actually an integral part of any design solution.





It should be noted that when working with a government customer, all ambiguities and ambiguities in your design decisions will always be interpreted in favor of the government. To avoid such blind spots, through trial and error in logging requirements, a design quality assessment checklist was developed, which listed the main sections that were to be reflected in the design decision as needed . Thus, any design solution should be checked from the following positions.

1. List of customer requirements (which will be implemented as part of the design solution).
2. List of definitions and abbreviations.
3. The list of normative documents regulating the automated process.
4. (use case), :
   
   
   
   
   • ( , BPMN – , : , ) ;
   • ;
   • ( ) — ;
   • ( , ).
5. :
   
   
   
   
   • , ;
   • (UI) ( , , ); 
   • () .
6. :
   
   
   
   
   • API;
   • () «» ( );
   • () «» .
   
   
   , « » ( 2011 ., 1). - , ().
7. :
   
   
   
   
   • , () , ;
   • , () .
8. () , , . ( ) . ( ), , () , . «» .

I repeat - this is not a fixed structure for a design solution, this is a formal list of questions ( checklist), the answers to which should, if necessary, be reflected in one form or another in the design solution. As practice shows, if development in relation to one of the elements described above is not expected, it will be better if you indicate this explicitly in the design solution. Or almost explicitly (don't scare the customer). The main criterion is an unambiguous interpretation. It is important not to overdo it so that instead of solving the stated requirement, five new ones are not born as a result of its approval. For example, the phrase "Reference of object types should contain only actual values" and the phrase "The reference of types does not provide for storing the history of changes" mean the same thing, but the second phrase will most likely lead to the fact that you have to describe and implement versioning mechanisms this very handbook.When forming design decisions, it is important to understand that its purpose is to fix the rules by which you are guaranteed to hand over the requirements associated with these decisions.

, , , .

Much (if not all) of the project depends on how the customer's representatives imagine the end result. Therefore, already in the initial stages, designing user interface layouts is key to the success of the project. Clarify and specify the customer's requirements in terms of an external description of the software product that he understands. The dialogue with the customer's representatives, based on the discussion of the screen layouts, proved to be much more effective than the dialogue on the discussion of the input and output data formats and their transformation algorithms (the main sections in the IPR, created in accordance with GOST).



Working out within the framework of design assignments all elements of the user interface, in addition to the transparency of understanding the implementation boundaries, also provides a solution to a number of problems:

1. . , , UI, , .
   
   
   
   
   
   : . . ISBN: 978-5-91180-090-1
2. UX- . , , ( ).
3. «» . UI , , – , ( « » ).
4. , «» . UX- . , 80% . , . ( ) : « ?». , , ( ) , , . , « ». «» . , , « ».

Source



I would like to say a few words about the principles of designing user interfaces for automated control systems. Despite the avalanche-like growth in the use of mobile devices, desktop computers and laptops remain out of competition for automated control systems used in government agencies (as well as for solving programming and system administration problems). Currently, a variety of tools have appeared for prototyping interfaces . However, explaining the specifics of using Figma or Axure in the interests of mobile devices loses 10% of the primitive ways that allow you to design 90% of user interfaces.ACS .



In my experience, to significantly reduce software development problems, you need to follow a few simple rules when designing user interfaces.



First of all, you need to decide on a general navigation scheme, on which, like a New Year tree, you can painlessly hang more and more new interface elements. In this regard, for automated control systems in my practice, the most effective scheme has shown itself, which is widely used in various IDEs . 



I will not give an example of IntelliJ IDEA or PhpStorm interface here, however, I will try to dissect the main components of such a UI into component parts, from the point of view of an analyst of an automated control system.



The interface built according to this scheme contains a collapsible vertical panel on the left, which provides navigation throughout the system. The presence of a vertical panel with sections containing hierarchical menus actually ensures the implementation of the “ three clicks ” rule .





Each of the menu options of the main navigation bar provides access to forms-lists of objects. Lists of objects (catalogs) and forms (cards) displaying these objects form the lion's share of the user interface. The unification of these two types of forms within the framework of the project and the formation of a navigation structure on their basis can significantly reduce the number of user requests associated with shortcomings in user documentation.



Within the framework of the description of any list form, the design must determine:

• list of displayed attribute fields;
• Requirements for list view modes (default display, grouping, sorting);
• requirements for the subordinate form associated with the list item (quick view card (table));
• requirements for the filter panel (selection of records according to a given list of attributes);
• description of group operations (simultaneous actions on several list items, for example: comparing list items, changing attributes for several list items, changing access rights for several list items);
• description of forms (panels) of operational statistical reports (monitoring) based on the results of the list selection;
• a description of the requirements for reports for printing and an algorithm for their generation;
• requirements for notifying users (external systems) when objects change.

When designing list forms, the following rules have worked well:

1. — , «» , .   (ribbon). 
2. , , :
   
   
   • — , CRUD: , , , ;
   • ( , );
   • ;
   • ( , , ).
   
   
   
3. ( .. ) . , . .

  :

•   ;
•   , (CRUD, , ..) ;
• /;
• list of possible information messages;
• ways to view the history of object changes.

A few words about the toolkit. As a result of trial and error during the implementation of various government projects, the following three approaches to interface design have proven to be the most effective.

1. In case, during development, changes to existing interfaces are required, you should not reinvent the wheel. Here Paint.NET showed itself best of all (with the help of which, by the way, pictures for this article were prepared). It doesn't make sense to redraw the forms again, it's easier to change the finished screenshot.
2. , — « »,   MS Visio . , , , , MS Visio, , , Windows. 
3. , -  , . , , . DHTMLX. XML-, , . (view), , . , , MS Visio. , , , « ».

Repeatedly, giving all these arguments to advanced developers, far from the customer's problems, I saw their fading eyes and listened to their expert assessment of the wretchedness and overload of the proposed UI. However, over time, after analyzing the experience of several projects, I noticed an amazing pattern: if a programmer zealously criticizes the backwardness and complexity of the developed user interfaces, this is a sure sign that the customer will accept such an interface with a bang.

Scaffolding and formwork

Usually people think a lot. But the trouble is, they think about problems, not about solutions to these problems.



David Allen

During the construction of houses, many auxiliary structures are used, which, after the completion of construction, are completely unnecessary. These are scaffolding and formwork . Remarkably, even non-professionals do not try to dispute the necessity of purchasing and maintaining these structures. In the IT industry, by contrast, you often see an "experienced" analyst struggling to immediately create project documentation that meets all the requirements.



However, in my opinion, without preventive registration and approval of design solutions, the created design documentation is suitable only for the formal closure of the contract and in the future harms the operation more than it helps. However, the design solutions and prototypes described above are not the only "auxiliary structures" in the analytical work.



Source



At first glance, it seems that everything depends on the experience of the analyst, and it is impossible to regulate the use of these auxiliary works. For example, how to take into account and regulate the work of an analyst who spent the whole day visiting a customer and the next day brought three gigabytes of all kinds of documents? Or that the analyst spent a week studying these documents? Is this good or bad? And you really can't answer that question if you don't know the results that make sense in light of the project's implementation.



That is why, within the framework of our project, a classification of the analytical work performed in terms of the results achieved was carried out. In addition to the design solution,Most of the software projects in which I had to participate required the analyst to develop analytical materials of the following types.

• Document analysis - a report on the results of the analysis of the customer's regulatory documents or project documentation.
• Analytical review - a report on the results of the analysis of solutions to the problem that has arisen (as a rule, a comparative analysis of new technologies or market trends).
• Information survey - a report on the results of a study of the existing business processes of the customer (formation of the as is model - " as is ").
• — ,   (use case).  legacy-.  
• — , ( ).  
• — , .

The second step towards predictable design was to define specific requirements for the intended analytical work. Based on these requirements, a JIRA problem description template was defined for each type of analytical material being developed.





The statement of the task for the development of analytical materials involves a brief description of the required results, and not a description of the analysis processes. So, for example, it is recommended to avoid phrases like "conduct a domain analysis ..." or "study the document."

A plan for the maestro 

Everything should be stated as simply as possible, but not simpler.



Albert Einstein

Often, when it comes to scheduling analysis and programming work, there is a lot of controversy about how to estimate the timing of the results in this case. However, the above analysis of this creative activity allows us to make the assumption that it is still possible within the framework of a software project. The first step towards this is breaking down the system design work into parts that can be checked at a frequency of at least once a week. It is necessary to strive to ensure that the analyst's labor costs for the formation of one design solution do not exceed 5 working days (in terms of volume, such a design solution should consist of approximately 20-30 pages - according to GOST R ISO / IEC 15910-2002). Accordingly, according to the same standards, a programmer should take a maximum of 3 hours to review the same design solution. 



It is important to understand that it is not necessary to make a technical project from a design solution . The design solution should cover only a small group of interrelated requirements, the result of which can be presented to the customer.



It is also important to avoid falling into the trap that Mary and Tom Poppendieck warn about when shaping a design decision., namely, not to become hostage to the myth that a detailed specification created in advance is guaranteed to reduce losses. As a rule, when agreeing on a design solution, the customer tries to cram everything that he can remember into this document. Therefore, when agreeing on it, it is important to ensure that the necessary minimum that will ensure the successful passage of the preliminary tests. At the same time, the key to success is not only a combination of quality, timing and cost, but also the satisfaction of the project participants with its results.



As a rule, to obtain the deadlines for the completion of tasks for analysis, an expert assessment of the contractor himself is sufficient, but in case of disputes, a pragmatic approach can be applied.... To increase the objectivity of the assessment of the labor intensity of tasks for analysis, an online calculator can be used , which allows you to plan and estimate the labor costs for conducting analytical work. Using this tool, you can create a list of planned works, clarify their wording, depending on the specifics of the project. For each of the planned works, the minimum, maximum and most probable estimate of labor costs are taken into account. As a result of the calculation, the expected complexity of the task is formed and the optimal time reserve is calculated, which must be left for insurance. The generated description of setting the problem for analysis can be copied directly into the JIRA problem description field.



In addition to the general attributes described in the article " JIRA: Project Boundaries", For each problem of the" analysis "type in JIRA, the following set of additional (custom) attributes was empirically determined.





Taking into account the above, let us clarify the previously given sequence of actions of the analyst on the implementation of tasks such as "analysis" in the interests of software development.



1. If necessary, the responsible analyst should schedule tasks in JIRA for conducting information surveys with customer representatives (these tasks are linked to the corresponding requirements).



It is advisable, before the meeting, as a first approximation, to form mock-ups of the user interface , which can be discussed with the customer. When conducting an information survey, it is necessary to discuss with the customer the main business process, from his point of view (user story - user story), alternative ways in which the customer sees the final result. 



I often met the opinion that the basis of an information survey is interviewing a competent employee who will tell you in detail about the features of the automated process. However, what is good for development in the interests of a commercial customer can have the most unexpected consequences for a government. I have repeatedly encountered a situation when it turned out that the description of the process, formed on the basis of the stories of gray-haired veterans, contradicts the key requirements of the current regulatory documents. And this was explained not by the fact that the analyst misunderstood something, but by the fact that the veteran "did this all his life."



Therefore, before meeting with subject matter experts, it is necessary to analyze the regulatory documents from the point of view of the regulation of the process intended for automation. It is important to understand that regulatory documents are also not the ultimate truth. Often, in an impartial analysis, regulatory documents always contain ambiguities and contradictions (the exception, as a rule, are documents “written in blood”). Here are some of the most common disagreements you should pay attention to:

• violation of the basic principles of classification , for example, when different signs are mixed within the same group (red, green, warm);
• construction of reporting documents based on attributes, which are not provided for;
• ;
• - ;
• — - , .

Resolving these regulatory conflicts is one of the key issues when meeting with customer representatives. In order to record this decision, as a result of the information survey, a protocol must be drawn up with an indication of the participants, place and time. The protocol is presented to the customer for clarification (e-mail is attached to the corresponding task). After that, the task for the information survey can be transferred to the status "completed". This JIRA task is transferred to the "closed" status after receiving confirmation from the customer about the protocol approval.



2.  Based on the specified requirements and the results of information surveys, a design solution is formed. The responsible analyst must coordinate it with the project manager and programmers (for each of them, appropriate subtasks are created). If the design solution has not passed internal approval during the working day, the task is transferred to the "pending" status (a signal to the project manager). Having passed the internal approval, the design solution is sent to the customer for review (if necessary, approval). All submission details are recorded in the comments to the task. While the design solution is on the customer's side, the task is transferred to the status "pending"



3.If the project solution is agreed (or if it is clear that the approval is being delayed, and the deadlines are running out), then on its basis the responsible analyst formulates tasks for development, testing and documentation. In this case, it is necessary to carry out a preliminary assessment of the labor costs for the implementation of the design solution (as the sum of the labor costs of the development tasks associated with this design solution). Based on this assessment, it is necessary to clarify the timing of the implementation of the related requirements.



4.  After agreement with the customer (a letter confirming this fact is saved in JIRA), the task of preparing a design solution can be transferred to the "completed" status.

To be continued 

Currently, software design for government customers is most often organized in accordance with the requirements of GOST 34 series. At the same time, advocating for the exact compliance of the final design documentation with this GOST, most of the customer's representatives often “forget” that, in addition to the documentation that is provided for testing the developed software, the customer must approve design solutions within the framework of the approval of the draft and technical designs. And even in the case when the draft and technical designs are agreed upon, it is not uncommon for the content to be ignored for the sake of unrealistic deadlines in full compliance with the form. This is especially true for the design of systems that are not directly related to life safety. So on one of the projects, one deputy head "taught life"talking about how he built a 500-page technical project using Wikipedia in one night. As a rule, completely different people have to disentangle the results of such “design decisions”.



In these difficult conditions, the approaches described here allow you to organize an iterative build-up of software functionality while maintaining the consistency of the implemented solutions, which corresponds to the principles of lean software development . On the other hand, the target settings of the described design solutions make it possible to compile documents on their basis that meet the "Procrustean" requirements of the customer at minimal cost.



The division of analytical work into elementary actions also made it possible to coordinate the actions of several employees with different levels of training and, as a result, naturally form a competency matrix for analysts of our project in LANIT , which I plan to discuss in the next article.



PSThis article is part of a series of articles called " Rules for the timely preparation of delicious software " which I use as an informal regulation of the team on custom software projects in the interests of government organizations. This series includes the following articles:

- " JIRA as a remedy for insomnia and nervous breakdowns " - the main idea for organizing work on a project using JIRA;

- " JIRA: project boundaries " - basic provisions for project unification and general requirements for all types of JIRA tasks;

- " JIRA: requirements management " - the key features of registration, clarification and control of the implementation of customer requirements within the proposed model;

- "Design solutions: playing by your rules ”- the main aspects of analytical work management and the formation of problem statements for developers;

Within the framework of this cycle, the following is being prepared for publication:

- " Matrix of analyst competencies " - criteria for assessing the level of maturity of analysts on custom software projects;

- " Where the troubles are hiding on the project " - the criteria (metrics) of the operational assessment of the current state of the software project.



The main label of this series of articles is to provide evolutionary improvement in the quality of software projects based on improved management efficiency. In other words, to form applied methods of growth at the levels of the CMMI model.

If you have figured out how to use JIRA more efficiently on your software project - share your ideas. Only in describing these ideas, avoid the phrase "somehow" and "somehow". I invite everyone to discuss. I am waiting for comments / suggestions / doubts / wishes in the comments.