- Единый формат (Markdown) устраняет фрагментацию.
- Git как основа обеспечивает версионность, аудит и совместную работу.
- Docsify + GitLab — лёгкое и быстрое решение без тяжёлых генераторов.
- Discourse как «песочница» — отличная идея для коллективного уточнения идей до финальной публикации.
Проблема: документирование в условиях многозадачности
Суета выполнения повседневных задач и частые переключения на пожары не оставлял времени на документацию. Вопрос оптимизации ее написания поднимался среди постоянных переключений между:
- CI/CD-пайплайнами
- мониторингом
- автоматизацией
- R&D
- поддержкой вышеперечисленного
- поддержкой заказчиков
- и детальным учётом времени
Возможности сосредоточиться на качественном документировании не было. А делать задачи кое-как я не умею.
Что требовалось:
- логировать действия
- дополнять записи картинками, ссылками и метками времени
- избегать смешения разных тем в одном черновике
- обеспечить возможность начать работать на одном компьютере, а продолжить на другом, включая мобильные устройства
- сохранять черновики автоматически так, чтобы они были доступны с любого устройства
- легко восстанавливать ход работ в будущем
- иметь возможность делиться черновиками на любых этапах работ.
Изначально идея заключалась в том, чтобы превращать черновик в полноценный рабочий документ и публиковать его в рамках проектной документации без привязки к этапам таймлайна. В итоге найденный подход позволил выйти за рамки локального использования и стал де-факто частью общей инфраструктуры знаний и часто на проектах стали использовать его как стандарт.
В итоге я построил гибкую, масштабируемую и человеко-ориентированную систему документирования , которая учитывает реалии работы инженера в условиях высокой нагрузки. Отказ от изолированных черновиков в пользу открытых обсуждений — особенно важное решение. Оно не только ускоряет доведение документа до качества, но и вовлекает команду в процесс.
Цель: документация как код
Создавайте черновики с расширенным форматированием и работайте с документацией так же, как с программным кодом. Это даёт несколько преимуществ:
- экономия времени на форматирование и конвертацию
- автоматическая генерация онлайн-документации
- наличие офлайн-режима (благодаря кешу браузера), что особенно ценно:
- в закрытых сетях заказчика
- в зонах без интернета.
“Заказчики высоко оценили эту возможность” - хотел бы написать я, но у нас в России скупо отзываются на полезные вещи. Для понимания, что формат прижился, мне достаточно оценки одного заказчика, который год пользовался закешированной страницей и пытался понять ребят с проекта, которые упоминали новые схемы и текст, которых заказчик не видел. А когда страницу открыли с другого компа, то поняли, что без интернета она ни у кого кроме него самого не открывается. Значит время на документацию было потрачено не зря.
Выбранный стек технологий
Основой стал формат Markdown, потому что он:
- поддерживается в GitLab, YouTrack, некоторых мессенджерах
- корректно распознаётся всеми современными LLM
- позволяет избежать проблем с версиями Word, «поехавшими» картинками и несовместимыми форматами.
Из черновика сразу можно получить:
- онлайн-версию
- строгий и красивый PDF в таком же стиле, как онлайн-версия.
Текущая практика документирования
Сегодня документация:
- Пишется в формате Markdown
- Хранится в GitLab:
- доступна всем сотрудникам по ролевой модели
- поддерживает многопользовательское редактирование
- Собирается автоматически в онлайн-версию:
- используется контейнер Docsify
- обновление происходит каждую минуту
- сайты публикуются в интернете через DNS (с именем 3 или 4 уровня для каждого проекта)
- Экспортируется в PDF с единым оформлением (на базе Vue.js), одинаковым для сайта и файла
- Диаграммы создаются в двух форматах:
- Draw.io (outline, для сложных схем)
- Mermaid (inline, прямо в Markdown)
- Экспорт диаграмм:
- в SVG (основной формат)
- иногда в PNG (для несовместимых платформ)
- с включением исходного кода диаграммы внутрь файла.
Модель трёх уровней документации — и её упрощение
Изначально я рассматривал три уровня документации:
- Черновики — личные, быстро меняющиеся заметки.
- Часто изменяющаяся документация — совместные рабочие материалы.
- Статическая документация — финальные, проверенные версии.
Однако я решил:
- отказаться от анонимности и изоляции черновиков,
- объединить первый и второй уровни в общие Wiki-черновики на базе Discourse
- оставить статическую документацию в GitLab + Docsify.
Хотя между вторым и третьим уровнями нет автоматической синхронизации, я считаю такой подход жизнеспособным: он упрощает поток знаний, снижает порог входа для коллег и ускоряет переход от идеи к публикации.
Инструменты и форматы
| Текст | Markdown (.md) | Основной формат написания |
| Хранение | GitLab | Версионирование, ревью, доступ по ролям |
| Онлайн-публикация | Docsify (в Docker-контейнере) | Автоматическая сборка сайта из Git |
| Черновики и обсуждения | Discourse | Коллективная проработка идей |
| Диаграммы (встроенные) | Mermaid | Блок-схемы, последовательности прямо в Markdown |
| Диаграммы (внешние) | Draw.io (.drawio → .svg) | Сложные архитектурные схемы |
| Экспорт в PDF | Docsify + единый Vue-стиль | Для офлайн-доступа и передачи заказчикам |
Что еще
В схеме есть еще над чем поработать:
- Синхронизация между Discourse и Gitlab
- Шлифовка процесса ревью и перевода в состояние готовности к публикации финальной версии
- Соблюдение ссылочной целостности
- Автоматизация публикаций
- Механизм обратной связи по найденным несоответствиям и оповещений по исправлениям.