Introduction

Documentation within the framework of an IT project/product sometimes has an unusual implementation. There are projects/products where, at first glance, everything is fine with the documentation, it comes out within the framework of contractual obligations, but it is very difficult to apply it. There are also reverse examples, when the documentation is designed well and written competently, everything is clear in it, but it is very outdated. Sometimes everything happens at once.

Is it not always clear how to include a new employee in the work? A novice has to distract more experienced colleagues. The most amazing case is when an IT project/product has its own mythical “Petrovych”, who knows how it works and can help you get used to it.

Formulation of the problem

As part of the article, I wanted to share approaches to working with documentation. Where is it formed, who uses what?

Essence

First, let’s determine who prepares the documentation within the IT project and where it can be used later. I will immediately note that the approach according to GOST 34, GOST 19 and other regulatory documents seems to me to be very good, but our task will be the formation of principles.

Points of documentation education (we will also indicate who makes it, but later)

The customer creates documentation on the goals and objectives of the project. It can be used as is, but, in my opinion, it is better to adapt it to the project in the form of schemes, user paths, etc.

The functional customer defines the sequence of actions in the software to achieve the result. Loves the description of processes in notations (BPMN 2.0 works best)

The project/product manager determines the sequence of work to achieve project goals/product benefits. He rarely writes documentation, or “borscht”, trying to fill in everything according to the PM BOK of the latest edition, using the templates received during certification (he himself sinned:))))

Analyst – creates tasks for development. There are different approaches, it is better to rely on the wishes and requirements of the team. Developers, for the most part, go to a meeting and explain what exactly they need

Development – ​​generates a minimum of documentation, is its user. If in your project development is involved in creating documentation, then something is wrong with it. Take care of the development, the team has an analyst, a technical writer, let them write

Testing – uses documentation from the analyst. They make up their documentation in a very diverse, in my opinion, the most difficult profession in IT, after full-time psychologists in IT companies whose salaries are average in the regional market 🙂

Infrastructure – forms documentation for operation and deployment of the project/product.

Technical support service – uses documentation from the analyst. Write instructions for users

Operation – applies the documentation that has been prepared in the infrastructure. Sometimes they complain about it (

Who creates documentation as part of project/product implementation

The project/product manager creates an overall picture for the project/product, which I include:

• Project/product goals — what the project output will look like. Helps with setting project objectives, Epic and Story formation (habr.com has great articles on this topic).

• Project/product milestones (road map) – project implementation control points. They help to evaluate whether we are getting there, whether the result of a particular milestone contributes to the achievement of project goals.

• Customer Journey Map – Description of the customer journey.

The project/product architect defines the technical boundaries of the project, as well as approaches and methods of integration into a single architecture, in which it is highly desirable to see:

• Component Diagram Contains a block diagram that displays the structural components and the relationships between the components.

• Integration scheme. Contains points of interaction with external and internal systems, subsystems, components.

• Description of interaction channels. Contains a description of information exchange methods and indicators of exchange channels.

The designer describes the guideline (Web-UI kit) together with the front-lead. This is a very important remark, since the guideline will allow to restrain the flight of creative thought of all participants of the project/product (I understand that the creator and the customer cannot be forbidden to envision, but the speed and quality of development will suffer greatly from excessive creativity. What to do with testing without a guideline is a separate and very specific question). And the task of the designer includes:

• Description of interface elements and components

• Description of fonts, colors, etc.

• Joint selection with the development, if necessary, of the library of components (I saw how the standard element of the calendar, which is in the library, was developed for almost 3 months:), and the time was correctly written off:)))

The business analyst prepares a description of the implemented processes in the system. In particular:

• Description of end-to-end business processes. Description from the point of appearance of a need in the system to the point of satisfaction of the need.

• Description of use cases (Use Case).

• Description of data for testing (Someone will say that this is a question of testing, and I will express my disagreement. A business analyst communicates with a functional customer. He must demonstrate functionality, and data from it, and testing his tasks is enough).

The system analyst prepares a technical description of the software implementation:

• ER diagram

• Sequence diagram (sequence diagram)

• Description of interaction methods (REST, SOAP, GRPC, etc.)

• Description of interaction with message brokers, etc.

development There is a nuance here. In my opinion, development should include only technical documentation that will complement the picture of all previous documentation. According to the idea, if some kind of documentation is required from the development (we will put information about the deployment of the system, code writing rules, agreement on approaches in parentheses), then at the previous stage, someone did not work a little.

Testing. In my opinion, the basic documentation for testing is use cases and test data, of course, except for specialized ones. Testing is an extremely exciting and time-consuming process. They simply never write tons of documentation.

Infrastructure. This includes everything related to DevOps methodology (DEvSecOps) and operation. This is a deployment diagram (deploy diagram), description of system configurations (of course better in git), etc.

Technical writer This is an employee who acts as an editor for the mandatory documents required for software development. For example, this is the user’s manual, administrator’s guide, and other documents used by technical support, operations, the customer, and the functional customer.

Let’s highlight the approach to work with documentation

Let’s quote the Agile Manifesto: “A working product is more important than comprehensive documentation.” Now I will share a little of my thoughts on this matter.

1. In order for the product to be of high quality, at a minimum, it is necessary to clearly formulate the goal of the project/product and allocate a set of tasks to achieve the goal.

Example: We were all told at school in mathematics lessons, and some during physics lessons: “To solve a problem, it is necessary to describe: given, find, solution.” We will supplement this algorithm from the school with a decision method and get what should come from the project/product manager.

2. From setting a development task to writing a user manual, there is only one document—the use case. It is usually written by an analyst, and with an indication of the main path, an alternative path and negative scenarios.

Example: The statement of functional development from the analyst went with a description of examples of use. Based on them, the system analyst will be able to describe the technical part of the implementation; development – to understand what the user wants; testing – to check the correctness of the functionality; technical writer – finalize the user manual; and the user – to understand how the functionality works. Note that most of the team members use the created document (!) at the staging stage.

3. You can split your wiki system into 2 parts. This will make it possible to understand what is currently being developed and what is already being used.

   • Working functionality. The technical support service is responsible for it.

   • Functionality under development, which the analyst is responsible for.

Example: After the completion of development, the functionality is transferred to support. Support reads the document and makes sure they understand whether they can adequately help the user understand the new functionality, notify users of the changes and provide instructions on how to implement the new functionality.

4. Development should generate documentation only when it is truly necessary. They have their own very important tasks that no one can solve for them.

5. The document must have a responsible.

6. The text must be understandable to a mentally healthy person.

Пример: Мои папа и мама! Я живу хорошо, просто замечательно. У меня все есть, есть свой дом, он теплый. В нем одна комната и кухня. Я без вас очень скучаю, особенно по вечерам. А здоровье мое не очень. То лапы ломит, то хвост отваливается. А на днях я линять начал. Старая шерсть с меня сыпется, хоть в дом не заходи. Зато новая растет чистая, шелковистая, так что лохматость у меня повысилась. До свидания, ваш сын, дядя Шарик.

It is difficult to read the letter from Prostokvashino:))) My work experience shows that this is the most cited description of the state of affairs on the project.

Conclusions

Documentation during the implementation of an IT project/product is necessary. The main source of documents is the analyst. With the right approach and due diligence, documentation can be kept up-to-date. It is important to remember that the documentation should be sufficient to understand the current situation and include new team members in the IT project/product implementation process. The rest is superfluous.