why we created our product for Docs-as-a-Code

By product documentation, I mean the documents that the customer receives along with the product, and which are necessary for successful deployment, configuration and operation. This leads to the following technical requirements:

Versioning documentation along with the product. This is especially important if the supplier supports several versions of the product and, accordingly, their documentation.
Well managed content architecture: reuse of texts, substitution values, generation of different sets of documents from the same source texts.
Documentation generation on APIs, databases, generation of documents from structured data received from external systems.
Various output formats: branded website for clients, printed forms, documentation in the distribution kit.
Localization.

Some of these requirements can be implemented using a wiki system. But the solution is expensive both to develop and to maintain. The main disadvantages of the wiki system for working with product documentation:

Complex versioning.
Heaviness and clumsiness with large volumes.
Loss of content due to frequent changes in voluminous texts.
Inability to generate API documentation, complexity or inability to work with structured data.
Difficulty setting up output forms. As a rule, a separate solution is made for them.

Benefits of the Docs-as-a-Code approach

For products with a regular release cycle, simultaneous support of several versions and documentation in different formats and completeness (for internal use, clients or customers, regulatory institutions), the optimal solution is the Docs-as-a-Code approach. The essence of the concept is that work with documentation is carried out according to the same principles as code development:

Storing and versioning documentation in a version control system, usually together with the product code.
Easy integration of documentation updates with task management systems.
Using logical test markup, lightweight markup languages understandable to a wide range of technical specialists: developers, testers, analysts, technical writers, managers.
Joint development of documentation, review and approval of documentation according to code review rules.
Developing rules for formatting documentation separately from content.
Organization of automatic testing, assembly and publication of documentation as part of standard DevOps processes.

The Docs-as-a-Code approach ensures reliable and transparent work with content and does not require separate labor-intensive operations to design content during its development.

Features of compiling documentation on Platform V

SberTech almost immediately decided to switch from Confluence to Docs-as-a-Code. And, like many companies, we were faced with choosing a tool that would make it easy to work with documentation. In our conditions it was profitable to make our own product:

Extensive product line: more than 80 software products from more than 200 software components.
Large production team: more than 2000 employees.
Documentation standard and internal standards governing product development.
The need to generate documentation for various types of APIs.
Frequent changes in requirements for the composition of documentation and its delivery.

Platform V GetDocs – a product for producing documentation in the Docs-as-a-Code paradigm

Platform V GetDocs is a simple and convenient tool for developing Docs-as-a-Code documentation and documentation site. Supports all necessary scenarios, is easily expandable and meets the needs of development teams and technical writers at SberTech.

Main functional features and advantages:

Simple and flexible text markup: MyST Markdown, reStructured Text. Support for substitution values, reuse of texts, inclusion and exclusion of texts based on assembly characteristics.
Support for working with different repository configurations:
- Documentation monorepository: information about all products in a dedicated repository.
- Separate repository for documentation for each product.
- Single repository for product code and documentation.
Documentation assembly:
- Various output documentation formats: static archived site for the distribution, printed forms PDF, DOCX, web version for the documentation site.
- Assembling sets of special-purpose documentation, for example, for registration in the Unified Register of Russian Software, etc.
- Collection of API references from source codes and specifications: OpenAPI, AsyncAPI, GraphQL, Java API, gRPC, JSON‑RPC.
- Display structured data in the form of separate documents or within one document (JSON, XML, YAML sources, etc.).
- Simple assembly management through the interface and the ability to assemble both individual sets of documentation and the entire site.
- High build speed: less than 1 minute for one set of documentation in development mode, about 5 minutes for publishing documentation on the site for readers.
Documentation check:
- A report with one-click navigation to the source of the error in the repository.
- Customizable and easily updated rules from internal guidelines and company brand books.
- Checking API references.
- Checking the integrity of links and site configuration.
- Checking the structure of documents and sections.
- Checking texts with illustrations, logical markup syntax, Russian grammar.
- Search and reconciliation of named entities.
Agreement and publication:
- Separation by levels of readiness for publication: documentation in development, approved and ready for publication, published on the website.
- Control of publication of finished documentation on the website.
- Synchronization of content between different installations (internal site and external sites for clients).
Documentation display:
- A single display style for all content for different sources of source files: documents in MD/RST, API references, structured data.
- Two display modes on the site: for the documentation developer (extended with additional tools, for example, going to the documentation source, going to the validation report) and for the reader.

Technical implementation of Platform V GetDocs

The product is implemented in the form of microservices packaged in Docker containers. They can be deployed in seconds on any machine with any operating system running Docker. Sphinx with the MyST Markdown parser connected is used as the document generation engine. The check is performed using a whole set of tools: Vale, mdlint, OCR, and its own solutions.

We have also added configuration to the product for deployment on a Kubernetes cluster. Using Platform V GetDocs on Kubernetes with its rich ecosystem provides significant advantages when administering, maintaining and extending the product. For example, we did not reinvent the documentation assembly interface, but simply deployed Argo Workflows and configured the necessary pipelines there in YAML format.

Out of the box we received integration with a corporate authentication system and a version control system, a visual history and progress of builds, convenient logs at each stage of the build and a list of received artifacts.

To ensure that all sets of documentation were in the same style and were checked according to the same rules, we moved website and printed forms templates, verification rules and configuration of the main sites into separate repositories.

Platform V GetDocs includes two loops: documentation assembly and documentation site. In a simplified form, the product architecture is presented in the diagram.

Main advantages of technical implementation:

Docker images provide a unified and secure environment for the functioning of components in any environment.
Microservice architecture allows you to expand and selectively update the product without completely rebuilding and deploying the entire solution.
Functioning in a Kubernetes cluster provides high speed, availability, automatic fault tolerance and scalability of the solution, which is especially important with huge volumes of constantly updated documentation. Additionally, we can automatically update and deploy new components in a matter of seconds, and in case of errors in development, quickly roll back to stable versions. And all this without any downtime!
The combination of Sphinx and MyST Parser provides tools for flexible documentation: rich semantic markup, easy markup extension, mixed use of MD/RST, complex tables, inclusion/exclusion of content based on characteristics, wildcard values, single source, localization, configurable templates for different formats of the generated documentation. Additionally, we replaced conf.py with simpler YAML.
Flexible customization of the documentation site template.

In the following articles we will talk about the implementation of our product, share recipes for organizing documentation for technically complex software products and show how Platform V GetDocs simplifies your workflow.