The problem: documentation in multitasking environments
The hustle of performing everyday tasks and frequent firefighting left no time for documentation. The optimization of writing it was raised amidst constant switching between:
- CI/CD pipelines
- monitoring
- automation
- R&D
- supporting the above
- customer support
- and detailed time tracking
There was no opportunity to focus on high-quality documentation. And I’m not good at doing things half‑assed.
What was required:
- logging actions
- enriching entries with images, links, and timestamps
- avoiding mixing different topics in one draft
- being able to start working on one computer and continue on another (including mobile devices)
- automatically saving drafts so they’re accessible from any device
- easily reconstructing work history later
- sharing drafts at any stage of the process.
Initially, the idea was to convert a draft into a full‑working document and publish it as part of project documentation without being tied to timeline phases. Ultimately, the approach discovered allowed me to step beyond local use and it became de facto part of our shared knowledge infrastructure and is now used as a standard on projects.
Goal: documentation as code
Create drafts with rich formatting and work with documentation just like software code. This provides several advantages:
- saving time on formatting and conversion
- automatic generation of online documentation
- offline mode (thanks to browser cache), which is especially valuable:
- in customer’s closed networks
- in areas without internet access.
“Customers love this capability” — I’d like to write, but we’re stingy about useful things here in Russia. To understand how well the format has taken root, it suffices for me to hear a single customer who used a cached page for a year and tried to make sense of colleagues talking about new diagrams and text he hadn’t seen. And when that page was opened from another computer, they realized that without internet access it wouldn’t open on anyone else’s machine but his own. That means the time spent on documentation wasn’t wasted.
Chosen technology stack
Markdown format became the foundation because:
- it’s supported in GitLab, YouTrack, some messengers
- it’s correctly recognized by all modern LLMs
- it avoids versioning problems with Word documents, “broken” images and incompatible formats.
From a draft you can immediately get:
- an online version
- a strict and beautiful PDF in the same style as the website version.
Current documentation practice
Today’s documentation:
- Written in Markdown format
- Stored in GitLab:
- accessible to all employees via role-based access
- supports multi‑user editing
- Automatically assembled online:
- using the Docsify container
- updated every minute
- websites published on the internet through DNS (with a subdomain level 3 or 4 for each project)
- Exported to PDF with consistent styling (based on Vue.js), identical to website and file styles
- Diagrams created in two formats:
- Draw.io (outline, for complex diagrams)
- Mermaid (inline, directly inside Markdown)
- Exporting diagrams:
- SVG (main format)
- sometimes PNG (for incompatible platforms)
- including the original diagram code embedded in the file.
Three‑level documentation model — and its simplification
Originally I considered three levels of documentation:
- Drafts — personal, quickly changing notes.
- Frequently updated documentation — collaborative working materials.
- Static documentation — final, reviewed versions.
However, I decided to:
- abandon anonymity and isolation of drafts,
- merge the first and second levels into shared Wiki drafts on a Discourse platform
- keep only static documentation in GitLab + Docsify.
Although there’s no automatic synchronization between the second and third levels, I consider this approach viable: it simplifies knowledge flow, lowers the entry barrier for colleagues, and accelerates the transition from idea to publication.
Tools and formats
|||
| Tool | Format / Technology | Purpose |
|---|---|---|
| Writing format | Markdown (.md) | Primary writing format |
| Storage | GitLab | Versioning, review, role‑based access |
| Online publishing | Docsify (Docker container) | Automatically assemble a site from Git |
| Drafts & discussions | Discourse | Collaborative ideation of ideas |
| Inline diagrams | Mermaid | Blochschemes, sequences directly inside Markdown |
| External diagrams | Draw.io (.drawio → .svg) | Complex architectural diagrams |
| PDF export | Docsify + unified Vue style | Offline access and handing over to customers |
What else
The scheme still has room for improvement:
- Synchronizing between Discourse and GitLab
- Polishing the review process and transitioning drafts to final ready‑to‑publish version
- Maintaining link integrity
- Automating publications
- A feedback mechanism for identifying inconsistencies and notifying about corrections.