how we created a new version of the documentation for the Rest API

Hello! My name is Sergey Vostrikov, I head the Market and integrations department in Bitrix. In other words, I help develop Bitrix24 functionality, available to developers of circulation solutions and individual customizations. This means REST API and everything “around” it – documentation, Bitrix24 Market showcase, solution developer account, etc.

The Bitrix24 REST API includes just too many methods, events, widget embeds and other nuances. Without documentation, this is, of course, completely impossible to deal with. And although it cannot be said that we did not have documentation, we must admit that over time the developers accumulated many complaints about it.

We recently showed the developer community our new documentation and can finally talk about how this project came about, how we worked on it and what we plan to do next.

The changes had been brewing for a long time – problems were accumulating, the existing platform required too many resources, entering materials through the admin panel into information blocks was becoming increasingly difficult, not to mention the difficulties with automating the process with such “technology”.

I’ll add that in the requirements for the third version of the Rest API, which (spoiler!) is currently in development, we included automatic generation of documentation from the product source code, instead of continuing to manually write signs describing methods.

However, we did not wait for the release of the new Rest API – we had a lot of work ahead of us, we decided to prepare in advance. In addition, we will be supporting the current version of the REST API for a long time, so good documentation is still needed for it.

New documentation

When planning work on a new version, we conducted a survey among developers to understand what needs to be changed first. So we formulated several goals for ourselves (in addition to the task of automatically generating documentation from source code):

1. Bring the content up to the standard accepted in the technical documentation for the API. Each method should include a detailed and complete list of parameters, their types, relationships with other methods, examples of calling the method in the main web development languages, a detailed example of the returned data, a complete list of possible errors with descriptions of these errors.

2. To create a single information space entirely dedicated to the Bitrix24 REST API, and transfer into it information that was previously stored in several courses and a reference book of methods.

3. Rebuild the documentation structure so that, first of all, it helps you quickly dive into the REST API, quickly complete the first request, quickly find ready-made typical scenarios for using the REST API, and not miss our recommendations for more complex cases.

4. Create conditions that will help external developers quickly share their practical experience and suggest improvements to the documentation right in it, on the spot.

5. Create conditions for quick localization of documentation into other languages, as well as simplify the inclusion of code examples in different programming languages ​​or using different SDKs.

It may seem that all these goals are achieved primarily by changing content and have little dependence on technology. But, in fact, we needed to completely rebuild the process of creating documentation, and this could only be done by changing the platform. It is this experience that I would like to share today.

New format and new platform

The industry standard for technical documentation has long been markdown. It's not as redundant as html, but it supports formatting, is friendly to technical writers, is intuitive when working with version control, and translates well to a wide variety of final documentation forms.

Almost all platforms for creating technical documentation can work with markdown – they all support certain markup extensions, are integrated with Github and provide the necessary functionality. We looked at several solutions and settled on the Russian Diplodoc from Yandex. A big plus for us is that we are constantly in touch with the developers, they promptly help us.

New processes

Choosing a platform is not so much a choice of a “documentation generator” as a radical transition to the “Documentation as Code” Using our artificial intelligence CoPilot in Bitrix24, we translated all existing documentation into markdown/yaml format and posted all materials in the open Github repository.

We no longer work with documentation as a set of texts. We work with it as program code. And external contributors in the form of application developers are now also part of the process. Instead of “Leave a comment”, as was the case in the old documentation, anyone can now make a change to the materials via a pull-request or create an issue on Github. Both are quickly processed by the team of authors.

The materials preparation cycle now looks like this.

Internal product developers, having received a task from the documentation team, provide materials directly in markdown. They commit method descriptions, parameters, and a basic example directly to the documentation repository. The basic example code for each JS method should make the most of all the method's parameters to show all the capabilities in the documentation.

Pull-requests from developers are checked by the authors of the documentation. Each author draws up a description of the method in accordance with our guides – we have a checklist of 20 points that must be completed when receiving the workpiece from the developers. At this point we reconnect CoPilot. Having a basic example in JS, we generate the rest automatically, a special bot “Example Generator” helps us with this. So we now show the required call examples for each method in 4 options at once.

The final acceptance of changes falls on the publishing editor, who, or rather, who, not only works with texts, but truly “knows how to use the Bitrix24 REST API.” It is she who decides whether changes can be allowed to be published, or whether improvements are required.

The entire documentation team is based in VSCode. Version control allows you to see exactly what changes were made, by whom and when. Colleagues can no longer imagine how they could work with documentation differently.

All changes in the main documentation branch automatically trigger the reassembly of the public version using Diplodoc, which easily solves technical problems: auto-generation of the general structure, auto-generation of the table of contents within each article of the article, auto-generation of links to the previous and next article, built-in mechanism for describing diagrams and diagrams.

So, diagrams and diagrams are now not pictures, but structures in markdown, which means they are also easily tracked in version control and conveniently localized:

I would like to point out another important advantage of the platform. We do not skimp on links in the documentation; we always add links to existing tutorials that use the described method. The platform itself monitors the integrity of the structure and does not allow you to make links “to nowhere”. This makes it much easier for authors to point the reader to where he can find related useful articles.

What does it look like now

New documentation we have already announced it in chats with developers, received a lot of positive feedback – we see that many enthusiastically accepted the idea spoil the documentation from Bitrix make changes to the documentation. For developers, this is a familiar, understandable and convenient approach. For us, being able to put developers directly into the documentation means we can integrate their hands-on experience using the REST API into the documentation for everyone else, and make changes faster because technical writers don't have to manually copy-paste stuff. They just need to comb the changes made by the developers to some of the text.

We are planning to develop a guide for external contributors; this will help make working with documentation even more convenient for both developers and our team.

Let's share for now examples design of materials and screenshots of the new version.

What's wrong with the English version?

As I wrote above, one of the goals of changing processes and technology was the need to update documentation for Western developers.

The English-language documentation had the same problems as the Russian-language documentation, but it was also far behind in terms of update time, since it was translated by our specialists from the localization team, who are also involved in the localization of the product itself. As a result, due to limited resources, the translation of documentation was greatly delayed.

By changing the technological process and switching to markdown, I wanted to ensure that we could include automatic translation into other languages ​​in this process. Now there is ChatGPT, there is our CoPilot, it can be used in many tasks.

We have already experimented with this – when making screencasts for English-speaking users, I wrote the script in Russian, then translated it using ChatGPT and sent it to the localization department for audit. Colleagues' edits were minimal, mostly stylistic – what can be called a matter of taste.

They had no complaints about the quality of translation of technical documentation using AI.

Now a technical writer collects ready-made changes once a week and, using CoPilot, translates them into English, checks them and sends them to the English version of the documentation, which is also rebuilt automatically.

Despite the growing trust in automatic translation using AI based on a three-story prompt, manual tasks remain, in particular:

1. Checking the assembly of translated documentation. We do not rule out that some markup fragments may be damaged during translation. Although this has not happened yet.

2. Replacing screenshots of the Bitrix24 interface with localized ones. Here artificial intelligence is still powerless, the problem is solved by the Documentation team.

With the new platform and translation from CoPilot, nothing stops us, we can quickly translate documentation into any languages.