analysis of the possibility of using the Docs-as-Code approach in MySklad
In September 2024, services such as Miro and Notion left the Russian market, and before that Atlassian left the Russian market with its Confluence and Jira products. My name is Pavel Mokeev, I work as a systems analyst at the MoySklad company and I propose to talk about how knowledge bases were at risk of loss and what to do to prevent this from happening again.
What is documentation?
Let's look at the problem:
once some part of the documentation was written
adjustments were made to it every day
the day comes when the accumulated documentation becomes inaccessible
Using an online record-keeping platform carries the risk of losing progress due to a decision that is beyond your control. The vendor may deny your organization’s employees access to the system or completely delete the accumulated information. But maintaining documentation the old fashioned way in files with the .doc extension is not a panacea. In order to work with the file, a program license is purchased. If you prohibit this, you may again find yourself in a situation of restricting access to data. On the plus side, in this situation the files themselves are not lost, and the information can be restored.
Thus, the concept of documentation becomes closely related to the form: file extensions, articles in Confluence, pages in Notion, directory structure with files on Google Drive or Yandex Drive. If you simplify the form of documentation, then what remains is knowledge expressed in text.
Is there a need for special text styling in the app for small text notes? The essence can be written in two lines without complex markup tools – tables of contents, headings, highlights and underlines.
Are diagrams always needed? In my practice, most often what I want to depict in a complex diagram can be described by a table or a multi-level list.
Documentation Tools
This way the documentation form becomes simpler. Simplifying the requirement for a documentation tool to capture knowledge, we get the following conclusion:
The tool should allow you to edit text and save it in a human-readable format in files
Many different services and programs meet this requirement, which frees up the hands of those who need to work with this documentation.
But another problem arises – working with such a file is difficult: it is simple text without headings, font changes, multi-level lists, tables and other functions that advanced word processors and online services have taught us.
When the question of replacing Confluence arose in MySklad, we compiled a list of requirements that the new tool must meet. I wanted it to be as good as the usual functionality of Atlassian’s brainchild. Here are some of the requirements that have been developed:
Editor WYSIWYG: in editing mode, the article should look the same as when published
Commenting on articles and article fragments: users leave comments on an article or start a comment thread on a selected fragment of article text
Links to other articles within the documentation are preserved when the article hierarchy changes
In addition, we wanted to solve a number of problems that Atlassian was not happy with, so we expanded the list:
Documentation is stored within the company's infrastructure and does not depend on the vendor
Review tool: user can prepare a new article or changes to an article for review before publication
After looking at the list, we realized that it would be difficult to find a ready-made solution.
What does Docs-as-Code have to do with it?
Then we decided to look at the situation from a different angle. Some of the requirements for the tool turned out to be imposed due to the fact that we are accustomed to certain processes. For example, a WYSIWYG style editor is not required to capture knowledge, and comments on fragments of articles last for several years.
Next, we looked at the solutions that are already used in our company:
We are excellent at storing code in repositories – it’s convenient and reliable
We have a clear code review process, and technically it is ensured using a version control system and repository hosting
After all, we are already writing documentation in the form readme.md files in repositories. It seems that from these ingredients we can assemble an instrument that will completely satisfy us.
Our recipe
Having understood our own capabilities, we decided to record what is needed to apply the Docs-as-Code approach:
During the research, we decided that we would eat this pie piece by piece and decided to test the approach on architectural documentation. And here's why:
It is expected that architectural documentation will be maintained by developers: unlike other specialists, they are more knowledge holders and have experience working with Docs-as-code tools
Architectural documentation can be decompose for iterative workfocusing on a single service and its interactions. We plan to use the framework C4-model: we describe the general context of services and go deeper into each
The documentation contains many technical diagrams, which will allow you to gain experience with writing diagram codes
Let's take a closer look at the points that will make up the Docs-as-code approach in MySklad.
Markup language
A markup language is a way to capture knowledge by specifying the structure of the text. There are different markup languages and notations on the market: AsciiDoc, MarkDown, reStructuredText, Wiki markup and others. We chose between Markdown and AsciiDoc.
MarkDown looks attractive: it is simple and easy to read without the need for additional tools. Supported for an audience of users of popular services: readme.md in repositories with code in GitHub and GitLab, Trello, Redmine, export from Notion, markup of messages in Telegram and others. The choice was not made in his favor for the following reasons:
Language does not have one correct interpretation. Choosing one dialectyou will have to select publishing tools only for it
The language does not support tables with merged cells
AsciiDoc is visually different from MarkDown, but the principles are similar. This language is standardized, and any tool that works with it should recognize it equally. Like MarkDown, it is interpreted in the Gitlab and GitHub UI, meaning files written with it will be readable when the repository site is opened. AsciiDoc has a richer syntax than Markdown: it supports tables with merged cells and native plugins (such as a table of contents).
In addition, a file written with AsciiDoc contains links to other files: when displayed, these are included as fragments in their own text. Using this functionality, you can separate sections of an article into separate files, which will improve the experience when reviewing changes and allow you to publish different versions of the same article for developers, support staff and users.
Chart image
Most knowledge can be written down as text. In this format, it is possible to unambiguously describe the connections and sequences between fragments of the subject of documentation. Moreover, it does not matter what exactly has to be described – microservice architecture, business rules or legislation. With a strong desire and the proper degree of dedication, you can even describe drawings of parts and projects.
However, graphical representation in some cases simplifies the process of immersion and helps the reader understand the subject of the description, so it should not be neglected. What is important to us when working with diagrams?
When documenting architecture, we often talk about class diagrams, C4-model, etc.
Images created in image editors such as Miro or the built-in Confluence draw.ioleave wide scope for creativity, which is inappropriate for unambiguous interpretation. When it comes to reviews, your head starts to hurt when comparing the previous version of the diagram with the new one. What to do?
We plan to use a tool like PlantUML. This is a diagram description language that allows you to generate images according to certain rules. The code written in this way is converted into a diagram. No matter how many times the image generation is started using this code, the picture will be the same until until the code itself is changed.
Another feature of PlantUML is that the more detailed the code is written with an explicit indication of the order in which the elements are displayed, the more readable the image is created. Thus, the tool helps improve the quality of diagrams. Below is a simple example: In the first diagram, the flow of activities is constantly changing its direction.
@startuml
hide footbox
title Заказ пиццы
customer->manager ++: Создать заказ
manager->kitchen --++: Приступить к готовке
kitchen->manager --++: Готовый заказ
manager->delivery --++: Передать в доставку
delivery->customer: Передать готовый заказ
deactivate delivery
@enduml
We make a small change – we indicate the order in which the participants are displayed and their type – and the flow of action now makes only one turn.
@startuml
hide footbox
title Заказ пиццы
actor customer
participant delivery
actor manager
participant kitchen
customer->manager ++: Создать заказ
manager->kitchen --++: Приступить к готовке
kitchen->manager --++: Готовый заказ
manager->delivery --++: Передать в доставку
delivery->customer: Передать готовый заказ
deactivate delivery
@enduml
The types of charts we use most often are:
Sequence diagrams — allow you to display the interaction between process participants
State diagrams – universal chart type. You can use it for its intended purpose, describing the final and intermediate states of entities, or show creativity by describing arbitrary processes.
C4-model diagrams is a set of diagram types that apply the principle of describing the architecture of applications at a larger scale – from the general use of actors to the code. To work with PlantUML there is special plugin.
Thus, we take advantage of the following advantages of the generated diagrams:
Images are created automatically from code. The resulting image provides unambiguous reading
When agreeing on changes, the reviewer sees the lines that have changed in the diagram code and evaluates the overall visual component instead of examining the image for new connections or lack thereof
The use of generated diagrams does not exclude the use of other images in the documentation, such as screenshots or photographs.
Version control system
What is a version control system?
Imagine the situation: an employee was instructed to make a change to a text file that must not be lost under any circumstances. To protect your data before work, it is better to make a “before changes” backup copy. During the work process, various working versions of the text appear, which need to be saved and offered as a ready-made solution. At each such fork, a backup copy of the file is made again and again.
At the same time, another employee was assigned another task with edits to the original file. As a result of joint work, a single text should be obtained. A difficult situation, because each of the employees could make edits to the same paragraphs.
So, a version control system is a tool that helps to collaborate: it compares text line by line and combines the result into a single whole. For developers and related roles, the described concept of work is no longer new. There are various technologies used for this, but the favorite and, in my opinion, the industry standard is Git.
We decided not to invent anything new here and took Git. Factors that influenced our choice:
The company already uses this technology to work with the code base. This means that:
Many employees can already work with it and transfer expertise to new roles: analysts, testers and technical writers
Other tools that are compatible with this technology are used – GitLab inside the infrastructure (we'll talk about it later) and IDE
Git has broad support from the developer community, which means there is clear textbooks and answers to any related questions
Repository hosting
To simplify the definition, a repository is a directory that stores a project with documentation and its versions: the main one, drafts of changes made, previous versions and all, all, all copies of the changes that were made earlier. It obeys the rules determined by the selected version control system.
Hosting is placed on your own computer or server within the company's infrastructure. However, as with version control, using a specific technology helps you work with it in an efficient and predictable manner.
Examples of repository hosting products are GitHub And GitLab. And again, we choose a solution that is already used in our company – GitLab. We use both its main data storage functionality and other functions:
Preparing changes for merging and executing a merge request
Deploy – checking the correctness of the recording format and publication of documentation on the site
Conclusion: You can choose more than just one repository hosting option. Choosing a version control system fundamentally narrows the list of options used, but documentation can be distributed among several hosting sites.
Publishing to the site
This is the final point that we mistakenly tried to address in the first place. If you have completed the previous points, then you need to decide:
Do you want to additionally publish a specific version of the documentation, or is what the repository hosting UI provides sufficient?
Who will be the user of this documentation and should the most extensive version of the documentation be published for them?
If you need to reduce the volume of published knowledge, what principles will guide you in dividing the documentation into separate files?
Perhaps the answer to the last question will force you to reconsider your choice of markup language. This list of questions is not finite and can be expanded to determine the value and necessity of publishing knowledge on a separate site.
Which tool should you choose? We decided to follow the usual path and prepared a publication for pages in Confluence. Those who have dealt with the API provided by Atlassian know that the text format of articles is non-human-readable HTML with a set of additional tags. This is where the AsciiDoc markup language helped us. We used a ready-made utility to convert articles to Confluence format without extensive research into markup language compatibility.
Why was Confluence chosen? The vast majority of company documentation is stored there today. We use this tool every day and have become accustomed to it, and administrators have user groups set up to provide access to different sections. As a result, Confluence turns from an article editor into a wiki site, which already implements several functions:
Saving links between pages
Indexing and powerful content search
Access content according to rights level
Commenting on articles and discussion within the text of the article
And also many others that we take for granted.
What is the result?
Everything that was written about above is the result of preliminary research. We prepared a system for working with documentation as code and carried out initial testing of processes related to making changes and publishing them. Now we plan to scale this system to other pieces of documentation and train development teams to work using this approach.
The research was strongly influenced by the work of Robert Martin “Clean Architecture. The Art of Software Development”:
The main way to keep software flexible is to have as many options available for as long as possible. What are these options that you need to have? These are details that don't matter.
Any software system can be broken down into two main elements: policies and details. The policy embodies all business rules and procedures. Politics is the true value of the system.
Details are everything else that allows people, other systems, and programmers to interact with the policy without affecting its behavior in any way. These include input/output devices, databases, web systems, servers, frameworks, data exchange protocols, etc.
Because of this, the Docs-as-code approach became more technical for me. Knowledge is use cases, business rules and restrictions, that is, they act as policies. Technologies that you use for this (how to write, where to write, how to control changes, how to show, etc.) – these are the details. Parts that can be easily replaced.
To reduce risks, documentation should be made independent of Confluence, just as an application should be independent of the framework in which it is written. Documentation and documentation should be treated the same as product development in a startup. Yes, in the early days you used frameworks to speed up development, but over time they can turn into dependencies.
We are going to apply our work and try to tell you about the results. I invite you to share my skepticism, optimism and experience. Thank you for your attention and see you again!
