And do you have good documentation?

Building an information system is a long and complicated process. Assessing the quality of an already built system is equally difficult. Users may like it or not, subjectively it may run fast or slow, its architecture may be scalable and modern or quite the opposite, and the code itself transparent and efficient or resembling Italian spaghetti. Among these many indicators, we often overlook the quality (or even existence) of the solution's documentation.

Two sides of the coin

Having worked in IT for many years, I have noticed two interesting trends in the subject of documentation. The first is that many novice programmers, internal IT departments and companies providing “low-cost” IT services do their best to leave no documentation behind. The word “none” also includes situations in which, after a year-long project of 1,000 man-days, the preparation of documentation and training closes in 10. We know very well that these 10 days are just a fig leaf covering what we do not want to show directly.

We have become so accustomed to this low-quality documentation that I often encounter the question during business negotiations: “And why is this documentation so expensive?”. I'll admit that this question makes me think of the attitude of suicide pilots who only take half the fuel on a trip, because they're not going to come back anyway. This is further emphasized by the fact that after handing over such well-made documentation, the words are said: “this is the best-made documentation I've ever seen”. And this would probably be very encouraging if I didn't know how low the bar was set.

What to document?

The question arises - what should be documented. The simplest answer is: everything.

Starting with documents that arise during the project, such as business analysis, system architecture or test plan. In addition to this, we need code standards that are the same for the entire organization, security, CI/CD processes, repository layout or how to document the code itself. In turn, after the project is completed, documents describing how the system works, user and administrator manuals will be useful.

Of course, specific IT areas will require additional forms of documentation. Using the example of the data area which is closest to me, we will additionally need: a data model, a document describing the mapping, transformations, business and technical meaning of the data, orchestration standards, and documentation of reports.

Why document?

I'll say from experience that there is nothing better on a programmer's first day at a new company than to be told that he or she will be faced with a SQL procedure that has 4,000 lines of code and not a single line of documentation. Hints like “you'll guess”, “ask the business” or “it's not our fault that the author of this work got laid off” only accelerate the decision to look for another place of employment.

Without good documentation, losing a code author employee is a drama. Without good documentation, trying to expand the team with new specialists - drama. Without good documentation, the code author's attempt to remember what the code does after not looking at it for a year - another drama. Without good documentation, an IT system turns into “legacy” the moment it goes live.

Article published in Insurance Weekly No. 12/2024