# Markdown, GitLab и Docsify: как стандарт документирования **URL:** \ **Category:** Основная\ **Tags:** документация, gemba\ **Created:** [24.Октябрь.2025 21:46:50 UTC](https://forum.gitgraphity.ru/t/markdown-gitlab-i-docsify-kak-standart-dokumentirovaniya/257 "2025-10-24T21:46:50Z")\ **Posts on this page:** 1\ **Showing post:** 1
**Author:** ![ivan](https://forum.gitgraphity.ru/user_avatar/forum.gitgraphity.ru/ivan/32/42_2.png) [@ivan](https://forum.gitgraphity.ru/u/ivan)\ **Post date:** [24.Октябрь.2025 21:46:50 UTC](https://forum.gitgraphity.ru/t/markdown-gitlab-i-docsify-kak-standart-dokumentirovaniya/257/1 "2025-10-24T21:46:50Z")
![Молодой человек сидит за столом, окруженный множеством экранов с кодом, в то время как из компьютера поднимается столб дыма. (Подпись к изображению от AI)](https://forum.gitgraphity.ru/uploads/default/original/1X/e46225fc4933d2c86426d958fa301c4ec2e18b2a.png) > - **Единый формат (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](http://Draw.io)** (outline, для сложных схем) - **Mermaid** (inline, прямо в Markdown) - **Экспорт диаграмм** : - в SVG (основной формат) - иногда в PNG (для несовместимых платформ) - с включением **исходного кода** диаграммы внутрь файла. ## Модель трёх уровней документации — и её упрощение Изначально я рассматривал три уровня документации: 1. **Черновики** — личные, быстро меняющиеся заметки. 2. **Часто изменяющаяся документация** — совместные рабочие материалы. 3. **Статическая документация** — финальные, проверенные версии. Однако я решил: - **отказаться от анонимности и изоляции черновиков** , - **объединить первый и второй уровни** в общие Wiki-черновики на базе **Discourse** - оставить **статическую документацию** в **GitLab + Docsify**. Хотя между вторым и третьим уровнями **нет автоматической синхронизации** , я считаю такой подход жизнеспособным: он упрощает поток знаний, снижает порог входа для коллег и ускоряет переход от идеи к публикации. ## Инструменты и форматы | | | | | --- | --- | --- | | Текст | Markdown (.md) | Основной формат написания | | Хранение | GitLab | Версионирование, ревью, доступ по ролям | | Онлайн-публикация | Docsify (в Docker-контейнере) | Автоматическая сборка сайта из Git | | Черновики и обсуждения | Discourse | Коллективная проработка идей | | Диаграммы (встроенные) | Mermaid | Блок-схемы, последовательности прямо в Markdown | | Диаграммы (внешние) | [Draw.io](http://Draw.io) (.drawio → .svg) | Сложные архитектурные схемы | | Экспорт в PDF | Docsify + единый Vue-стиль | Для офлайн-доступа и передачи заказчикам | ## Что еще В схеме есть еще над чем поработать: - Синхронизация между Discourse и Gitlab - Шлифовка процесса ревью и перевода в состояние готовности к публикации финальной версии - Соблюдение ссылочной целостности - Автоматизация публикаций - Механизм обратной связи по найденным несоответствиям и оповещений по исправлениям. --- _[View the full topic](https://forum.gitgraphity.ru/t/markdown-gitlab-i-docsify-kak-standart-dokumentirovaniya/257)._