- Unified Format (Markdown) eliminates fragmentation.
- Git as a foundation ensures versioning, auditing, and collaboration.
- Docsify + GitLab – a lightweight and fast solution without heavy generators.
- Discourse as a “sandbox” – a great idea for collectively refining ideas before final publication.
Problem: Documentation in Conditions of Multitasking
The hustle of performing daily tasks and frequent switching to fires left no time for documentation. The question of optimizing its writing was raised among constant switches between:
- CI/CD pipelines
- monitoring
- automation
- R&D
- supporting the above
- customer support
- and detailed time accounting
There was no opportunity to focus on quality documentation. And I don’t know how to do tasks poorly.
What was needed:
- log actions
- supplement records with pictures, links, and timestamps
- avoid mixing different topics in one draft
- ensure the ability to start working on one computer and continue on another, including mobile devices
- automatically save drafts so that they are available from any device
- easily restore progress in the future
- have the ability to share drafts at any stage of work.
Initially, the idea was to transform a draft into a full-fledged working document and publish it as part of project documentation without being tied to timeline stages. In the end, the approach found allowed going beyond local use and became de facto part of the overall knowledge infrastructure, and projects often started using it as a standard.
In the end, I built a flexible, scalable, and human-oriented documentation system that takes into account the realities of an engineer’s work under high load. Refusal of isolated drafts in favor of open discussions — especially important decision. It not only accelerates the refinement of the document to quality but also involves the team in the process.
Goal: Documentation as Code
Create drafts with rich formatting and work with documentation just like you do with software code. This gives several advantages:
- saving time on formatting and conversion
- automatic generation of online documentation
- offline mode (thanks to browser cache), which is especially valuable:
- in closed customer networks
- in areas without internet.
“Customers highly appreciated this opportunity” - I would like to write, but we are stingy with praise for useful things in Russia. To understand that the format has taken root, it’s enough for me to assess one customer who used a cached page for a year and tried to figure out the project guys who mentioned new schemes and text that the customer had not seen. And when the page was opened from another computer, they realized that it did not open for anyone but him. So the time spent on documentation was not wasted.
Selected Technology Stack
The basis is the Markdown format because it:
- is supported in GitLab, YouTrack, some messengers
- is correctly recognized by all modern LLMs
- allows you to avoid problems with Word versions, “gone” pictures and incompatible formats.
From a draft, you can immediately get:
- online version
- strict and beautiful PDF in the same style as the online version.
Current Documentation Practice
Today documentation:
- Is written in Markdown format
- Is stored in GitLab:
- available to all employees based on role-based access
- supports multi-user editing
- Is automatically assembled into an online version:
- uses a Docsify container
- updates every minute
- sites are published on the internet via DNS (with a 3 or 4 level name for each project)
- Is exported to PDF with a unified design (based on Vue.js), which is the same for the site and file
- Diagrams are created in two formats:
- Draw.io (outline, for complex schemes)
- Mermaid (inline, directly in Markdown)
- Diagram export:
- to SVG (main format)
- sometimes to PNG (for incompatible platforms)
- with the inclusion of the diagram source code inside the file.
Three-Level Documentation Model – and Its Simplification
Initially, I considered three levels of documentation:
- Drafts — personal, rapidly changing notes.
- Frequently Changing Documentation — collaborative working materials.
- Static Documentation — final, verified versions.
However, I decided to:
- abandon anonymity and isolation of drafts,
- combine the first and second levels into common Wiki-drafts based on Discourse
- leave static documentation in GitLab + Docsify.
Although there is no automatic synchronization between the second and third levels, I believe this approach is viable: it simplifies the flow of knowledge, lowers the entry barrier for colleagues, and accelerates the transition from idea to publication.
Tools and Formats
| Text | Markdown (.md) | Main writing format |
| Storage | GitLab | Versioning, review, role-based access |
| Online Publication | Docsify (in Docker container) | Automatic site assembly from Git |
| Drafts and Discussions | Discourse | Collective idea development |
| Diagrams (embedded) | Mermaid | Block diagrams, sequences directly in Markdown |
| Diagrams (external) | Draw.io (.drawio → .svg) | Complex architectural schemes |
| Export to PDF | Docsify + unified Vue style | For offline access and delivery to customers |
What Else
There is still work to be done in the scheme:
- Synchronization between Discourse and GitLab
- Polishing the review process and translating it into a state of readiness for final publication
- Maintaining link integrity
- Automation of publications
- Feedback mechanism for found discrepancies and notifications about fixes.