Documenting is a separate item of project revenue.

Introduction

In recent years, I have had the opportunity to work in several rather different IT companies related to the development or integration of various solutions from government to commerce. Participated in and oversaw a considerable number of projects. But almost everywhere a weak point is the same - documenting solutions being developed.

It is the headache and feed for the corporate toad of the developer company. From the point of view of a “standard integrator”, this is a kind of side process, the results of which are mainly needed to close the formal requirements of contracts. Do not be demands - how much could free up resources! Yes, and do not distract from the work of the true breadwinners of the company: vendors, managers and to some extent programmers. The picture of completing and organizing the work of the “capacities” on the development of documentation is a separate sad song, not for this article.

There are situations where some of the contractual documentation is useful within the company. I saw this. There are situations when projects were closed solely thanks to documentation. And I saw this. But in general, these are just exceptions.
')
I, hand on heart, do not like this situation.
I, occasionally developing documentation, do not agree to be a squander of corporate resources.
And I have something to say about this.

Dear sales, product and project managers - let's more actively promote documentation. Let's earn on it!

Why do customers need documentation?

A global question - why does a customer need any documentation for a specific solution? Not the kind of “tick” that the top management will ask of them, or which is required by the regulatory framework of the industry. Everything is clear with her, she is just needed. Speech about the documentation, which is actually used in the future and has an applied value.

There is no universal answer to this question. Depending on the circumstances, an honest answer will vary from "... d is not needed!" To "and how can it be without it?". However, there is a certain dependence. The longer the estimated period of life and development of the decision, the more important is the role of documentation in it.
Because the longer it takes:

To customer:

• Adapt the solution to changing realities in terms of functionality and task coverage. And fast.
• Expand the scope of automation, including through integration with other systems.
• Learn alternating (sometimes - often a lot) staff.
• Update its own regulatory framework related to the application of the solution (regulations, departmental regulations, process instructions, job descriptions).
• To keep records, planning and optimization of the cost of the solution. At a minimum, to know for what it has already been paid for and not to fall for the auditors to re-pay the same with the ensuing allegations of double funding or money laundering.
• Provide the necessary level of enterprise security — including by eliminating dependence on a single supplier / developer of a critical decision.

Performer:

• Transfer competencies to develop solutions (in 2 years, half of the team “in the subject” will change, then more).
• Transfer competencies in quality assurance and solution support - testers and support staff change even faster.
• Update the information support for the product manager.

If the customer does not cope, he will face very tangible financial and temporal losses with the prospect of understanding, developing and implementing the solution again. If the performer fails, he will simply cease to be a performer. Immediately or after some time.

It turns out that a competent set of documentation (it is literate, and not large) is able to significantly extend the life of the solution.

Another rather weighty argument related to the lifetime of the solution is its cost in the calculation for a certain period of time. Considering that the cost of a solution for a customer “per year” is the sum of all expenses divided by the number of years, his full-time toad must be vitally interested in that the denominator in this formula is as large as possible. It's one thing if the system for 6 million will work for 2 years, and quite another if at least 3. This is a whole million savings every year.

Of course, developers can argue, “So what? After two years, we just scoop another solution for the same money. We are better! ” But first, it is not sporty. And secondly, it works a limited number of times, after which it becomes more difficult to find a customer.

At the end of the conversation about the significance of the service life I will give the following thought-observation. Suddenly useful as an argument of cognition of value in comparison. In a system operated for 6–8 years, the program code undergoes several refactorings and is rewritten from scratch (and often by another performer on other technologies). But the documents describing the needs of the customer and the main ways to meet them, except that they are updated a couple of times. Slightly.

What to offer the customer?

The composition of useful documentation can vary considerably from project to project, however, I can recommend the following general approaches to its definition.

In most cases, including projects for commercial structures, when determining the nomenclature and content of the documentation, you can build on a bunch of GOST 34.201-89 and RD 50-34.698-90. It would not be superfluous to also ask in advance whether the customer has his own departmental or corporate standards (or even personal preferences of the decision maker).

With a large number of documents, it is desirable to group them in stages and / or generality of content in order to simplify the work on the coordination and subsequent planning of work.

I can offer the following categories that I use myself:

1. Pre-design. It will include documents that precede the design of the solution. Including:

• survey reports;
• concepts;
• feasibility studies;
• technical tasks, etc.

The benefit from them often happens where the customer himself does not fully control the situation and wants to know what is happening, for example, in its branches. Or wants to once again thoroughly think whether he should begin serious work (with the exception of TK, about him below).

2. Project. All that relates to the projected (but not yet implemented) solution. There may be quite a lot of project documents (see, for example, the same GOST 34.201-89) and from project to project accents of usefulness and attractiveness of certain documents for a potential customer may shift, however, documents containing the description are usually the most popular:

• tasks that automates the proposed solution;
• technical details about the functionality and internal design of the solution;
• the necessary actions to ensure that the projected solution can earn “as it should be” (data migration strategy, personnel training plan, certification of workplaces, etc.).

The benefit is, firstly, in understanding by the customer of what the performers conceived and evaluating the expected results at a relatively early stage. Secondly, in understanding the scope of forthcoming works and their compliance with the means and terms. Third, relative independence from a single developer. Well, something else on the little things.

3. Working. This includes information about how the designed solution should be placed / configured / supplied with initial information in very specific working conditions. Including:

• layout schemes for hardware at the automation facility;
• power supply and communication channels;
• configuration file descriptions;
• description of the primary content of reference books and databases;
• description of diagnostic methods, etc.

It is invaluable if the customer plans to exploit and accompany the solution on his own (at least partially).

4. Operational. Anything that explains how to work with a solution. First of all, these are various manuals, instructions and technical regulations. In contrast to the design and work, in the usefulness of the operational documentation of the customer have rarely convince. Except for cases when the customer received a deep emotional and emotional trauma from the previous use of the results of the work of unfortunate writers.

5. Administrative regulatory. If the solution involves intervention in the customer's organizational structure (from changes in individual functions and reassignment of individual employees to changes at the level of the organization's hierarchy), then such events in reputable offices are accompanied by documented. And rarely when the customer is eager to do this work himself. This is a good reason to offer to ease his already heavy burden (and the budget, of course). Documentation in this category includes:

• administrative regulations for the provision of services or performance of functions;
• regulations for the operation of units;
• regulations on structural divisions;
• draft orders that introduce those or other organizational changes;
• job descriptions, etc.

6. Educational. I deliberately separate it from the operational. I propose here to include materials that in an organized manner prepare the customer’s personnel to perform their tasks with the help of our solution. Of particular importance are these materials in conditions of high staff turnover (call centers, retail outlets, etc.). To trainers include:

• training programs and monitoring the knowledge obtained by “students”;
• teaching materials;
• training courses (including audio-video).

7. "Miscellaneous." Depending on the situation, there may be a need (or desire) to develop documents that are difficult to categorize unequivocally into any of the categories listed above. For example, the protocols of information interaction between the customer and the third-party organization usually have signs of simultaneously administrative, design and working documentation.

I especially want to dwell on two documents. "Take them" out of context. It:

• Terms of Reference, which at the very beginning of the work defines the scope of the project and the main requirements for the solution.
• By testing and testing the program and methodology, the customer confirms that the tests provided for in it fully meet his expectations from the implementation of the TOR requirements (down to the level of goals and objectives). In other words, he officially confirms that the test system is exactly what he wanted.

These documents, in my humble opinion, need to be in any project in paper form with all the approving and approving signatures.

How to offer the customer?

A lot has been written on this topic, and much better than I can write. My humble experience only suggests that if you have a more or less literate documentation specialist, nothing prevents you:

1. Prepare the maximum, optimal and minimum set of documents that can reasonably be offered to the Customer in a particular situation.
2. Properly and systematically substantiate the merits of each of the proposed packages and each of its documents. Make a comparative table.
3. Culturally arrange all this in the technical and commercial proposals.

Instead of a conclusion ...

... I will share the story about the nomenclature of documentation and customer needs.

Somehow I had the opportunity to participate in the development of a serious solution for a very serious customer. When I saw the requirements, I was a little surprised: they developed the development of about 35+ documents of the technical project. That is, almost the entire 34th GOST.

To the cautious question, “Why do you need all this wealth?” The customer answered something like this: “The competing department from the neighboring Department has just accepted the system, which was staffed with 20 documents. We cannot allow our development to look less solid in the eyes of the general! ”

And you say - "not for sale!"