How to create a documentation portal from scratch

First of all, it was necessary to find our target audience, taking into consideration the market segment of Arenadata products.

We have identified three groups of readers that we believe were most relevant:

This does not mean that we have ignored other end-user categories, but we have decided to focus on this specific group first.

The next step was to determine the content structure of the future documentation portal, which meant deciding whether to include the following sections: User guides, Tutorials, How to, Concepts, References, and others. It was also necessary to take into account different levels of our readers (Junior, Middle, Senior) and adapt the content accordingly.

Although it may seem that the writing style is not so important, we paid special attention to it. In our opinion, without a uniform style the texts would be vague and difficult to understand. The main goal of our documentation is to present the information in a clear and concise manner so that users could easily find information on our portal.

It was also important for us to choose the right approach to writing documentation among "docs-as-code", "docs-as-product", "wiki-oriented", and others. We have chosen the "docs-as-code" approach where documentation is reviewed and processed using the same tools and practices as software code. It includes the use of version control systems such as Git, CI/CD automation, document versioning, creating merge requests for reviews, and the use of markup languages to write and format text.

We create solutions based on Open Source, so English language support wasn’t even a question. Rather, we have asked ourselves a different question: "How do we properly organize the process of writing bilingual articles?". Should we first do a release in Russian, and then in English — or vice versa. Either way, both of those options have proven unsuitable for us.

We have decided to release bilingual documentation simultaneously with each new release of our products. It is important to note that we do not translate documentation, but write from scratch in two languages. This approach has proven to be effective in terms of the timing and quality of documentation.

The ease of use of the portal was also a priority for us:

Having chosen the docs-as-code approach we started to think about the documentation engine. Documentation engines are specialized tools that facilitate the creation, structuring, and management of documentation. There are many such tools, including Sphinx, Jekyll, Docusaurus, MkDocs, Antora, GitBook, and others.

It was important for us to write the landing of the portal in the same programming language as the engine. This would allow us to customize the engine if its standard capabilities were insufficient to implement our ideas. As a result, this approach has been fully justified and has provided greater flexibility in managing documentation. This narrowed the choice down to the static site generator Antora. If it’s of interest to any of the readers, we will look more closely at the comparison of different analogues in one of our next articles.

However, the engine was not a panacea for us. In our case, only 5% is Antora, the remaining 95% is our own JS customization on top of it. But Antora is a good tool for technical writers because they write in the convenient AsciiDoc format.

We have been thinking about the possibility of using ready-made search tools for the portal, as well as our own development on the basis of ElasticSearch. Eventually, we came to the conclusion that the second option would be better for us, because we could improve the search ourselves. It may seem that to expand the functionality of the internal search engine is meaningless, but our experience has shown the opposite.

We realized that users would be less likely to use the website’s built-in documentation search, rather going to Google/Yandex and from there directly to the desired article on our portal. Nevertheless, we pay special attention to the internal search to make it as user-friendly and easy as possible. For this purpose, we have introduced product tags.

For writing documentation we use two-week sprints. They do not coincide with the sprints of development teams, but determine a set of articles that each writer has to write or edit during this time. It can be both descriptions of new features for upcoming product releases (these tasks are usually created by architects, system analysts, and technical program managers — TPM) and articles on basic topics unrelated to any version of the product (such tasks are created by the Head of TW). Sprints are useful to avoid accumulating a large amount of changes in texts and to proofread them in small chunks. Initially, we didn’t do sprints, but as the team grew, they became necessary. For over a year we used one-week sprints, and in 2024 we switched to two-week planning.

Tasks are created in the bug tracking system. While working on the article, a writer is guided by the information from the task (topic, recommendations for structure, links to the Open Source documentation, SEO recommendations), conducts an independent search in open sources, and actively cooperates with colleagues from related departments. Primarily with product architects, system analysts, technical managers, and, if necessary, software developers.

Important point: every writer specializes in a specific product, and also does independent testing of the documentation. In other words, writers perform all the steps mentioned in their articles. This includes deploying and configuring test stands on remote infrastructure in the cloud, installing all required services, writing and running SQL queries, as well as code in other programming languages, and much more. As we mentioned above, from the very beginning, it was important for us that technical writers do not play a purely paperwork role, but deeply immerse themselves in their products and test the processes described — and this approach quickly yielded results: sometimes technical writers are the first to suggest useful improvements or corrections for the products they describe.

All texts in AsciiDoc format writers create via GitLab — within separate branches in repositories with product documentation (one product = one repository). At the end of the sprint, for each completed task, a MR (merge request) is created, and the task is directed to a review. Currently, we have three types of reviews (following each other):

After all reviews are completed, the sprint ends and the next tasks are taken up. Note that the described workflow was not formed immediately. We changed it repeatedly, adapting it to the size of the team and current goals. For example, the aforementioned cross-review was introduced only in 2024. And since the end of 2023, each task in the backlog is supplemented with recommendations on SEO optimization: values of the title and description meta tags, suitable keywords, structure recommendations based on the analysis of similar materials in the network, etc. Below we’ll tell more about the role of SEO in our team.

As mentioned above, at the beginning of the project, we defined sections for future documentation (Planning guide, How to, etc.). But at the implementation stage we faced additional questions: is it better to convert the old documentation or write a new one from scratch? Which articles should be written first? And, importantly, how long will it take to release a new version of the documentation for each product?

We abandoned the idea of converting the previous documentation on Sphinx, because it was mostly irrelevant and contained both grammatical and factual errors. Like we said before, it was documentation for a startup our company was at that moment. So we decided to write all texts from scratch, although the tools for converting from RST to ADOC exist and have even been tested by us (for example, via the pandoc utility).

To answer the remaining questions, we prepared detailed content maps for each product, which described all future articles and their location in the website navigation menu.

Then, on the basis of content maps we created roadmaps, where the scheduled tasks were distributed among authors on a weekly basis.

The detailed roadmaps allowed us to answer when the first releases of updated documentation for each product would be ready. Of course, there are skeptics who will not believe that with such level of detail it is possible to meet the deadlines — much less those set a year or more in advance. However, practice has shown the opposite. For most products new articles were released as planned.

Currently, 80-90% of the original content maps are implemented for most of the products. When they are fully processed, we will find new topics for the articles. It applies only to scheduled articles. All changes regarding new product releases are processed as a priority as soon as we get the tasks from other departments.

But we no longer update the roadmaps. Now we create tasks in the tracker for 1-2 weeks ahead, because the team has increased significantly, and with the addition of a new role (SEO) more in-depth task descriptions were now required. But in general, roadmaps were quite useful during the first phase to set a certain pace of work, which we maintain to this day.

In all environments documentation is built automatically according to the pipelines configured by our CI/CD command in GitLab. We use 3 environments:

The division into environments was implemented quite quickly thanks to the functionality of Antora. Its playbooks in YAML format allow you to specify from which repositories and branches you need to upload ADOC files to the website build. Thus, in the Test playbook we specified the master branch, and in the PreProd playbook — all release branches (with the release* prefix).

At the moment of the PreProd build, Antora independently extracts the product version number from each release version of the code and saves it in the site structure. Then, this version number is displayed in the web interface — in the version selector. Thanks to this, the portal supports documentation versioning for each product.

Through the split into playbooks, we implemented another, no less important, function of our portal — multilingualism. Antora does not support the use of several languages "out of the box". It took us several days to figure out how to implement the language switch via a button in the UI. The solution was very simple: instead of one build for each environment, we started to make two builds — based on separate playbooks for Russian and English languages. We created two root directories in all documentation repositories: EN and RU. Accordingly, RU playbooks refer to the RU directories with the code, EN playbooks — to the EN directories. As a result, we now use 4 playbooks: EN/RU for Test and EN/RU for PreProd. And the entire website language is switched, as intended, via one toggle button in the top right corner of the page. This solution, despite its simplicity, is scalable: if necessary, you can always add an additional language without making significant changes to the existing code.

At the initial stage of development of the documentation portal, we did not have detailed style guides, since the elements of the web interface were being designed and developed in parallel with writing of the first articles. As a result, a lot of inconsistencies started to appear in the documentation of various products: file names were highlighted both in monospace and italic, different types of tables were used for the same purpose, etc. Therefore, the issue of internal rules for writing documentation became pressing very soon.

When writing style guides, we did not focus on Google, Microsoft, or other well-known styles often used in other companies. We had our own unique design, and, therefore, wanted to adapt our style guides to it as well.

As a result, we formed a set of rules for using the main components of the UI: fonts, tables, lists, code snippets, command output. We described both the standard syntax of AsciiDoc and the additional classes implemented by our frontend developers for the needs of our design: collapsible blocks, tabs, pagination buttons, cards, and more. Finally, on the basis of the most common errors, we developed a checklist for self-testing articles by authors before sending them for review.

In the first months after publication on the internal portal, style guides were actively supplemented, e.g. based on feedback from new employees. If a complicated case was not covered, we discussed it at the daily meeting and fixed in the rules. However, we have never sought to document "everything". We believe that form is important, but it shouldn’t take precedence over content. The currently approved rules are sufficient to make the texts for different products look unified, so the reader can always determine what each color, font, etc. means, regardless of the page it is used on.

Starting from the very first releases of the documentation, we described every change in detail and notified all interested employees via the company messenger. These messages were subsequently converted into a separate section Documentation releases on our portal. The most important advantage of this section for our clients and employees of other departments is that they no longer need to wait for the next digest in the mailing list or messenger — it is enough to open the page from time to time and independently track updates of the desired products.

It is important to say that the documentation release in our company is not equal to the product release. Yes, we try to produce documentation in sync with product releases, and most often the documentation release includes articles that describe product changes. However, the concept of the documentation release is broader: it may include other articles on various topics, which are not related to the new product release. Besides that, documentation releases may be published more frequently in comparison with product releases.

Releases of the products themselves are also described in detail — in the "Release notes" section of the documentation of each product. For easy reading all changes are grouped by version number and type: new features, improvements, bug fixes, misc/internal.