# Markdown и Git для документации и никак иначе

**Category:** [Основная](https://discuss.rabkesov.ru/c/main/4)
**Created:** 2025-07-06 00:14 UTC
**Views:** 36
**Replies:** 0
**URL:** https://discuss.rabkesov.ru/t/markdown-i-git-dlya-dokumentaczii-i-nikak-inache/78

---

## Post #1 by @ivan

<div data-theme-toc="true"> </div>

>`Новая папка(2)`/`Новый текстовый документ.txt` `Новый текстовый документ(2).txt`
> \- Где же я это записал...

# Тяжелые предпосылки

Вопрос оптимизации написания документов родился в суете выполнения задач. Частые переключения между пайплайнами, мониторингом, автоматизацией, RnD, поддержкой и детальным списанием времени не давали сосредоточиться на документировании.

![На девушке над головой горит огонь, символизируя технический сбой или неудачу в работе. (Подпись к изображению от AI)|689x394](upload://jzZukZ5y5ugxqQzhV4MPhRQiMxA.jpeg)

# Логировать историю

Мне требовалось логировать свои действия, дополнять тексты картинками, ссылками и метками времени, не допуская пересечений тем в одном и том же черновике. Делать нужно было так, чтобы потом можно было легко вспомнить ход работ.

>Несколько раз логирование Putty/Bash помогало восстановить запутанную последовательность работы на проде. Не игнорируйте такую возможность.

# Публикация

В дальнейшем я хотел превратить черновик в рабочий документ и опубликовать его в рамках проектной документации. В итоге получилось красиво выйти за границы.
Целью было создавать черновики с расширенным форматированием и работать с документацией как с кодом.

Это позволило экономить время на форматировании и переводе в стандартный публикуемый формат. 

# Онлайн-формат

В итоге формат Markdown+Git позволил автоматически генерировать онлайн-документацию. Бонусом стал офлайн-режим, доступный из кеша браузера. В закрытых сетях заказчика, в самолете и там, где нет интернета, этот режим очень пригодился. Заказчики тоже его оценили.

Формат Markdown  используется в Gitlab, YouTrack, некоторых мессенджерах и распознается всеми моделями LLM.

# Shared drafts

>Если ваша работа не связана с финансами, то ваши черновики не должны быть скрыты. Наоборот, позволяйте работать с ними совместно.

Мое стремление сделать черновики общедоступными дало толчок к созданию “документации как кода”. Команда девопс освободилась от безымянных текстовых файлов и проблемы поиска, "где это было записано?". Тут нет проблем с разными версиями Word, поехавшими картинками и тому подобным. Плюсом из черновика сразу получается онлайн-версия и красивый и строгий PDF.

# Документация сегодня

- пишется в формате Markdown (редактор Typora или аналогичный с автосохранением + коммиты в IDEA/PyCharm)
- хранится в Gitlab (доступна всем сотрудникам по ролевой модели, поддерживает многопользовательское редактирование)
- автоматически собирается в онлайн-версию в контейнере Docsify (обновление кода каждую минуту); сайты пробрасываются в интернет с помощью DNS
- легко экспортируется в PDF с одинаковым оформлением Vue.js как для сайта, так и для файла
- диаграммы создаются в формате Drawio (outline) и Mermaid (inline)
- диаграммы экспортируются в svg (и изредка в png для несовместимых платформ) и включают в себя интегрированный исходник

# Чего не хватает?

Большинству пользователей не интересно единое место, где хранится документация и что ее можно там редактировать в многопользовательском режиме. Редакторов-контрибьюторов единицы, а простых пользователей много. Для них важно быстро найти нужный документ в актуальной версии, легко им поделиться. Отсюда есть пара вопросов, каким образом:
1. Составлять автоматический список документации.
2. Ранжировать ссылки в тексте по актуальности документов (не в плане наличия свежих правок, а правок по сути - ведь никому не нужен документ, оказавшийся вверху списка только благодаря косметическим правкам).
3. Допустить режим мелких правок прямо в документе, без необходимости работы с исходником.
4. Актуализировать документацию "пачкой", когда некоторые части документации взаимосвязаны и частично либо полностью переиспользуются.
5. Генерировать документацию автоматически, поскольку она очень быстро устаревает.
6. Приводить к соответствию не только саму документацию, но и напоминать о необходимости скорректировать либо дополнить связанную реплику сотрудника в публичном канале или коммьюнити. По таким репликам в первую очередь складывается мнение об авторитетности (слова человека, имеющего отношение к документации, первостепенны нежели сама документация, это сложившийся факт).

Третий пункт уже встречается в некоторых платформах, например Discourse. А прийти к структурированной документации поможет ИИ.

---


**Canonical:** https://discuss.rabkesov.ru/t/markdown-i-git-dlya-dokumentaczii-i-nikak-inache/78
**Original content:** https://discuss.rabkesov.ru/t/markdown-i-git-dlya-dokumentaczii-i-nikak-inache/78