Documentation in software development

Intro

Good afternoon, dear community.
Let me introduce myself. I am a business analyst. I have been working in the field of custom software development for ten years, and recently I have combined the roles of analyst and project manager.

One of the painful issues in software development has always been and remains the process of documenting this development itself. Have you ever come to a project that has been done for a couple of years, but at the same time, you cannot deal with it, because of the documents there is one technical task, and even that is written at the very beginning and does not reflect half of the system's functionality? I've done it. And it is, frankly, a very sad and torpid spectacle.
Therefore, on all my projects, I try to initially build the process so that there is no unidentified and undescribed functionality, all team members receive timely information in time and there is peace in everything

So, to begin with, I will answer the main question: what is all this for.
There are several reasons.

1. Documentation provides a “common space” for a project. Any participant at any time can receive the necessary information both on a specific task and on the general direction of work.
2. The team speaks “in one language” - after all, it is much easier to understand a person reporting “an error in the function described in Use Case No. 12” than “a dumb bug in the garbage Vasya did a month ago.”
3. Documentation allows you to clearly delineate the areas of responsibility between the project participants.
4. Only carefully described requirements can be checked for completeness and consistency. “Knocked notes” is a direct and very fast way to ensure that the project boundaries crawl away with quick cockroaches, and the functionality, initially conceived, will not be mounted with the customer’s Wish list arising in the process.
')
For myself, I developed a set of basic rules that allow you to effectively document, plan and control the development in a comfortable environment for all participants.

1. Documentation should not be redundant and voluminous. We do not write documents for the sake of a pleasant tapping process on the keys, but in order to use them in our work. Excessive amount of text is annoying and difficult to read.
2. The whole scheme of documenting the project should be interconnected and logical. If there is a document in the schema that is not associated with any other document, then it can be safely removed from the schema.
3. The entire assessment of labor costs should be made only on the basis of the atomic tasks described. It is difficult to evaluate the development of the “data entry subsystem functional”, it is much easier to evaluate the tasks of “developing a Martian data entry form” and “developing a Martian list filter”. The smaller the estimated element, the more accurate the aggregated estimate will be.
4. It is always necessary to create lists of alerts to interested participants. The developer, who learns about the need for improvement three days before the release, is an evil and meanest meanness, an analyst who quietly changed the requirements and did not notify all interested participants about the need for improvement - the last pig, and the RP that allowed such a situation - the plague, cholera and an unpleasant person, who can not cope with their responsibilities.

I propose to the court of a respected community a documenting scheme that seems convenient, logical and correct to me. And - yes, it works.

So, what types of documents are used in the scheme.

1. Terms of Reference.
2. Private technical assignment (optional).
3. Use case.
4. Test scenario.
5. Bug Report.
6. User Guide.
7. Administrator’s Guide (optional).

The figure below shows the pattern of communication between these documents.


How it works?

TK

Initially, during the examination, a large technical task is formed.
It includes:
• glossary of subject terms;
• description of the subject area;
• description of the role system;
• description of functional requirements;
• description of non-functional requirements.
The requirements description in this document is fixed at the “upper level”, that is, we describe not specific actions, but only necessary functions. Requirements are optimally divided into semantic groups by subsystems.
For example , we describe the subsystem "Administration" with the functions "Create a user card", "Delete a user card", "Edit user card". These are the requirements of the upper level, there is no sense to go lower in the TZ.

Chtz

In case the system is large, it is reasonable to do the Private technical specifications for each subsystem.
ChTZ must contain:
• link to item TK;
• the most detailed information on each function;
• UseCases list for function.
Thus, the continuity of documents is realized, which allows, firstly, to unify their form, and secondly, to partially implement reuse, that is, to reduce the time spent on “writing”.
For example , we form CTZ on all the same subsystem “Administration”. It will contain the description of the function: “Card creation. It is necessary to implement the following functionality: calling a card using the “Create” button, card interface containing the next set of fields, saving a card using the “Save” button, canceling the saving using the “Cancel” button.

Use Case

Use Case - the essence of the use case, it describes all the actions that the user can take, and the response of the system to these actions.
Each Use Case must be tied to a CTZ item.
The most optimal, in my opinion, is the description format, which includes:
• Screen layout. Layouts can also be made complex, “clickable”, but, from experience, there is enough of a “wire diagram” made with the help of Visio or a similar tool. If modal windows are to be used on the form, they should also be drawn, the tables below for them should be duplicated.
• Diagram of screen actions, graphically describing the algorithm of the function.
• A table with a description of the fields. The following data should be placed in the row of the table: field name, field type, data entry restriction (logical checks, etc.), roles of users who can read / edit the field. If the field is calculated, then it is necessary to specify the formula for calculating the value.
• A table describing the action of the screen buttons. The row of the table should contain data on the name of the button, a description of the action for the click and the paths of the transition, if a click on the button suggests a transition to another screen, the role of users for whom the action is available.
It is also possible a small general description of the functional but, as a rule, it is simply not necessary.

Test case

Test Case, which is quite self-evident, should contain a description of test scenarios.
Ideally, each such document is tied to the corresponding Use Case, but it happens that it is logical to combine several Use Cases into one Test Case.
The best variant of the description format is a table containing in one column a description of an atomic operation involving the response of the system, in the second a description of the correct response of the system. For example, it is not necessary to describe the process of entering text into a text field, but it is obligatory to check the validity of the data when it is saved (by clicking the “Save” button).

Bug report

A little more I will be a cap: Bug Report arises in the process of testing the system as a tester's reaction to an error. Each document must necessarily refer to the corresponding Test Case.
The document must contain:
• screenshot of the error;
• description of previous actions. It is best to develop a template for such a description that is convenient for everyone - this greatly saves developers time when playing a bug;
• text description of the error itself.

User Guide / Administrator Guide

The most boring in writing, but, nevertheless, vital documents.
In fact, their formation can even be automated, if all the Test Cases and Use Cases were written with due diligence and properly executed.
I will not dwell on them, if suddenly the topic is of interest - I will tell you about how their compilation can be automated.

Conclusion

I hope that the article seems useful and interesting.
Naturally, I did not touch on many other issues of documentation in software development (for example, the use of standards, templates, process automation, etc.), but if the topic is interesting, I will continue to write with pleasure.