How we brought order to the documentation. From manual drive to full-fledged autodoc

Our path to putting the accumulated documentation in order can be divided into two parts. First we went through it manually, then we launched auto-documentation. First, I will tell you what and why we did manually, since without this part of the work there is no point in launching automation. The second part of the article will be directly about autodoc.

Let me make a reservation right away that the use of autodocs in b2c is unlikely to be so relevant, since everyone has the same general documentation. But in b2b it’s difficult without it.

We have a product of the CDI (Customer Data Integration) class – “Single Client”. The main documentation for it lives in Confluence. Each customer sees two different spaces:
– general documentation, which describes standard settings, rules, etc.
– documentation with the rules of a specific customer.

The problem is that the pages in these spaces are named the same. Moreover, pages in the customer space contain information from shared documentation (through the mechanism of incorporating text from one page to another).

Why was this inconvenient?

• Customers did not understand where whose settings were. It often happened that they first looked at their documentation, then the general one, and then came to us with questions: “Where do we have this? Why isn’t it written like that here?”

• Sometimes during implementations, when the documentation needed to be done quickly, the guys simply took one customer’s documents and made a copy-paste, since Confluence does not have an entire space template, there is only a template for a specific page. This all generated pages with irrelevant documentation, since something could have been done differently for the new customer. In my subjective opinion, the complete absence of documentation is much better than pointless copying.

• 30+ customer spaces in Confluence had different structures (although they described the same product, which was implemented according to a standard implementation process). They were created by different people at different times and made as they saw fit. While the company was small and separate teams worked with each client, there were no problems. When there were more customers and spaces, chaos began to multiply.

• Those same 30+ spaces brought fun to everyone when something changed in the product itself. For example, a new field appeared. Yes, Confluence allows you to include some pages within others. But each customer has his own data model, which means that it is impossible to beautifully combine both the general model and 50 custom fields of the client in one table. When adding a new field, you need to go to each space and add it there.

In general, the main ambush was that There seems to be documentation, but it’s unclear how up-to-date it is. We tried to describe everything, spent time, but the main question about the documentation is can she be trusted? – stayed.

With all this, our documentation was considered by customers to be one of the best. Because we write it in human language, with examples. But the actualization was frankly lame sprinkles ashes on his head.

Visual style

I’ll explain once again why you can’t do without the manual work stage. Without unifying the structure, we will not do anything with auto documentation. We need to understand what format the sections in this autodoc should be in to make it convenient. How can we compare them with the current ones, if the current ones are all called differently?.. Plus, different nesting: one customer has the module description in the “Modules” folder, while another has it hidden even further. We won’t even be able to compare and figure out if we did something wrong, for example, in the autodoc. So before you start automating, you first need to put things in order manually.

We started by asking support, where does it hurt the most? We received an answer: the customer is often confused about where his documentation is and where it is general. Nested pages and cross-links in Confluence played a disservice: the customer could click on the link and end up in a space with general product documentation, which in an ideal scenario he should not see at all.

We decided to make an explanatory plate for general documentation. Almost immediately we encountered the problem of banner blindness: people don’t notice banners and are automatically cut off from their attention zone.

We tried changing the background and fonts, but it didn’t work. The fact is that it is convenient for a person to work in a blue-gray color scheme. And for the difference to be noticeable, you need a clearly different style (that is, replacing dark blue with black, for example, does not work – people do not notice the difference). On the other hand, if you change it to something bright, then it’s already difficult to work: saturated colors draw attention to themselves, you want to immediately escape from the documentation.

Through trial and error, we came to the conclusion that it was enough to change the color of the menu so that everything else would be read normally, but at the same time the person would immediately understand that he was in a different place. And it’s convenient for the customer to answer: if the menu color is yellow, this is a general space.

This is what it looks like:

But even with this yellow color, in fact, everything turned out to be not so simple. When I proposed this thing, I unexpectedly encountered resistance from the guys – Well, Kamon, we lived before and it was normal, what a stupid color… We had real internal battles and a series of re-edits about who would re-edit whom.

Templates

What's next? Often customers and integrators need summary information about the installation and servers – IP and DNS-name, OS and its version, CPU, memory and disk, connection ports, application interface, admin panel, installation folder… Here we were helped by such a thing as templates in Confluence. I highly recommend using them. They are suitable, for example, for describing a connection about servers, because the IP and DNS name can appear dozens of times there. Plus, you can place dies in the template so that a person does not make mindless copy-paste, but sees where and what he needs to change.

What else is great about the template? A unified page structure, substitution variables, prompts for filling out (the text of the prompts is not displayed on the final page and is not visible to the customer), labels for reminders, clear instructions.

I show you what it looks like below in the screenshots.

There are, however, some difficulties with templates: We made them in the space of one customer, but we needed all 30+ clients to move to them. We set the task in Jira and started noting for which customers this had already been done. We made a rule: we deliver a release to the client and update his page using a new template.

This, on the one hand, allowed us to carry out the activity not in the form of a cleanup day or as an order, but to fit it into the work cycle. Why am I telling you about this? In my opinion, initiating change is easy, but carrying it through is difficult. Especially when it comes to monotonous work. And there is always a risk of getting stuck, stopping in the middle, when some customers were transferred to new templates, while others remained on the old ones.

At the same time, we have customers to whom we rarely deliver releases or who have little interaction with the documentation. We already worked with their spaces using the method of finishing subbotniks: every couple of weeks we tracked in Jira which customer pages we had not yet transferred to the new structure, and took them to work.

Restrictions

Our next problem: there were quite a lot of access restrictions for customers based on the documentation. But when a person creates a page in another space, he may forget to put a lock where the information is for internal use only. It is difficult to keep track of what is available to the customer and what is not. Here we found a simple solution: we leave everything in one space, and move what the customer should not see into a separate block.

It looks like this:

When putting the restrictions in order, we once again ran into the heterogeneous structure of the customer’s pages.

You had to comb through the entire space before you found what you needed to put into the restriction. We decided that we couldn’t live like this any longer. To begin with, we connected metrics to understand who is using which pages. For this, we have an excellent bot that can tell who has viewed a particular page and how many times. Essentially, we made Yandex Metrica for the entire Confluence. When we received the report, we were very surprised: It turned out that almost no one opens the cool documents that customers should read!

Solution: cloned the customer's space and created a new structure based on metrics. What is needed most often was moved to the first and second levels of the hierarchy. Yes, we found a ton of pages that we don’t know what to do with. They were labeled as needing updating. So, all the spaces of the “Single Client” customers were consistently transferred to the new structure.

During the translation, another point arose: what to do with irrelevant information? Here we decided this:

• delete, if it has been moved to other sections or is completely outdated and definitely will not be useful in the future;

• archive, if the information is out of date. But it is important to remember why it was done this way.

And finally, a little automation

As soon as we started transferring customers to the new page structure, there was another surprise. The realization came that the data model remains very mediocre. Where is the most up-to-date information about it? In code and in the database! We went to the programmers and convinced them to automate the unloading of fields from the code and database into the documentation. The reality shocked us – there were 20 fields, but now there are 40! Questions poured in: what kind of fields are these, and where are those fields?

It turned out that some of the system fields were not described in the documentation, since they are internal, and the customer does not need to know about them. And there are also virtual fields in the code that are not in the database. These fields, on the contrary, are important for the customer, but they were not initially included in the auto documentation. As a result, we marked in the code what to display in the dock and what not.

When we installed auto documentation, we started updating 60-100 pages for each customer every day. Problem? Yes. Firstly, it cluttered up the update feed a lot. Secondly, it was unclear when in reality something changed in the documentation. A new version of the page was created every day from scratch, even if the information on it was no different from the previous version.

The nuance is that after sending a request to update the page, Confluence formats the html according to its own rules. This means that if we string-wise compare the html before and after sending it to Confluence, we may get a mismatch due to reformatting. As a result, the stability of checking whether an update is needed was achieved through the use of hash codes. When generating documentation, we in any case create html for all pages. If the input data has not changed, then we will receive the same html every time. From this html you can calculate a hash code (we use md5) and save it on the same page in a hidden block. It turns out that before updating the page, we can request the current version and extract the hash code from it. Next, we compare the hash code of the new html and the current html. If they do not match, we refresh the page. If they match, we move on.

The bottom line: we always know which pages are generated automatically. Customers do not see this, since this information is stored in a hidden block. It allows us to instantly distinguish “automated” pages from “manual” documentation without manually correcting them. What it looks like is shown in the screenshot:

One of the goodies we received — automatic placement of cross-links between directories and fields that are filled with these reference values. This information (that a specific field, for example, “address type” is a classifier with five values: home, work, relative’s address, for correspondence, other) exists directly in the product code and is now automatically uploaded to the documentation. Previously, all links from the field to the directory were placed manually. This led to the fact that some links led to the wrong reference books by mistake, and some reference fields did not have a link at all to the list of possible values ​​in this field. So along the way, we also improved cross-referencing in the documentation.

Brief summary

So what do we have as a result?

1. Clearly separated common documentation and customer spaces.

2. Each client now has clearly separated open and closed parts of the space. We unified the structure of all customer spaces. Descriptions of all stands are now in the same style. This made it easier to onboard new employees, support customers, and move people from one client to another. Now it is always clear where to look for specific information in the space of any customer without fortune telling, but what is it called there and where is it located.

3. An up-to-date description of the data model has appeared, which is unloaded from the code. There is no point in editing the page quickly by hand, because later it will be automatically erased.

4. And yet, what was said in the previous paragraph is not a panacea. Over time, we realized that customers’ wishes do not always correspond to the code that is available. That’s why we made cutoffs in the autodoc where you can add manual notes that are not overwritten by automatic documentation updates. Yes, this is a manual solution to the problem, and you have to monitor it so that notes are made if necessary.

   

5. The best part is that there are fewer complaints and questions from customers;)

And a couple of recommendations for those who are starting to work with autodocs. Usually APIs are automatically described, but when you start to build a document from code, everything will depend on the programming language and how the code is written. First, I recommend looking for Open Source solutions – for example, Swagger. You can also find options for Java, but due to the size of the project, we use a self-written tool.

Be prepared for the fact that sometimes colleagues, due to their automatic nature, may not fully believe her. Sometimes people come to us to complain: they say there is an error in the autodoc. But in reality it turns out that there is an error in the code, and the autodoc simply reflects this. You can definitely trust a soulless machine, we checked;)