Документация, с которой удобно всем: Markdown и Git вместо Word и почты
Всем привет!
Как организовать согласование технических заданий, чтобы не терять историю правок и не пересылать документы Word по почте? Как организовать совместную работу над ПМИ? Как хранить документацию проекта так, чтобы всегда можно было ответить: кто, когда и зачем изменил требования? И при чём здесь ИИ?
Эти вопросы беспокоят руководителей проектов, системных аналитиков и технических писателей. Word даже с облачными решениями плохо справляется с версионированием документов: правки хранятся не все, история изменений живёт в почте, а автоматизация согласования отсутствует как класс. В этой статье я расскажу, как построить процесс работы с ТЗ (и другой проектной документацией) с использованием Markdown и Git: от структуры репозитория до pull request'ов вместо листа согласования. Подход пригодится командам, которые хотят прозрачный документооборот и готовят документацию к работе с ИИ.
Проблема: согласование ТЗ в Word — почта, облака и потерянные версии
Существуют разные варианты организации работы с технической документацией. Процесс написания технической документации может выглядеть так:

Сначала аналитик готовит документ в Word. По результатам кропотливой работы появляется первая версия документа. Получившуюся версию автор отправляет почтой (вложением или ссылкой на облако). Возможны варианты работы с облаком. Например, ссылка может вести на файл, или же на папку.
Рецензент просматривает файл и в нём появляются комментарии. Чтобы автор увидел замечания и вопросы, необходимо его уведомить. В ответ автору уходит письмо с приложенной обновлённой версией документа или информация об обновлении файла в облаке. Часто название файла в этом случае преображается и получает постфикс вида "..._в1_ком.docx".
Изучив комментарии, автор переводит документ в режим внесения правок и выполняет изменения документа по полученным замечаниям, даёт ответы на комментарии. Внесённые правки собираются в виде короткого резюме в таблицу изменений. Название файла часто меняется. Из него пропадает постфикс и повышается версия. В худшем случае название получает дополнительный постфикс к уже имеющемуся. Например, "...в1_ком_ред.docx". Появившуюся новую версию документа направляют по почте, и рецензент просматривает правки и ответы на вопросы в файле. Отработанные комментарии закрываются рецензентом. Если требуется, цикл правок повторяется.
В итоге появляется финальный документ, который маркируется в названии файла датой и версией. Комментарии удаляются, правки принимаются, чтобы получить чистовой вариант. Заканчивается ли на этом жизнь документа? Конечно, нет. Дальше в процессе разработки появляются детали и внезапные изменения - вносятся правки в файл. Позже в ходе тестирования появляются баги. Снова в документ дорабатывается.
Позже появляется обратная связь от маркетинга, пользователей, руководства и так далее, и тому подобное. Всё это требует внесения правок в ТЗ - доработки функционала или фиксации уже сделанных изменений.
Через какое-то время появится потребность выпустить глобальное обновление. В этом случае можно дорабатывать текущий документ для проектирования следующей версии решения, но потом нужна дельта, чтобы участники процесса не пытались выудить подробности изменений из бесконечного числа страниц файла или лога изменений. Либо мы можем сразу создать отдельный документ, но в описание первой версии всё же потребуется внести изменения, чтобы хранить описание текущего решения, а не пытаться воссоздать какой-то его элемент, перечитывая набор документов с правками.
Что не так с docx: проблемы организации совместной работы
При проектировании больших систем работает несколько команд. Зачастую отдельные компоненты являются общими или переиспользуются. Важно обеспечить контроль кто и когда вносит правки, иметь возможность назначить ответственных за документ. Возникает проблема непрозрачного документооборота.
Word не позволяет просматривать изменения в исторической перспективе - либо видны все правки одновременно (что затрудняет чтение), либо остаются только последние изменения. Таким образом, у Word отсутствует детальная история изменений.
В Word выпуск версии документа не является управляемым событием: номер версии приходится проставлять вручную — в теле документа или в названии файла. Отсутствует возможность реагировать на это событие и выполнять рассылки или какие-то другие действия - отсутствует автоматизация.
Даже если документ ежедневно обновляется в облаке - как контролировать работы аналитиков? Контроль возможен только по количественным показателям (например, по числу страниц), но этого недостаточно для оценки реальной работы аналитиков. В случае с файлами формата docx отсутствуют объективные инструменты контроля работы аналитиков.
Как организовать работу с ТЗ через Git?
Во времена работы с бумажными документами функции организации процесса документооборота мог взять на себя офис-менеджмент. Сегодня к нашим услугам системы контроля версий (Git).
Для разработчиков работа с Git уже стала привычной:
Сначала идём в архив и получаем актуальную версию документа. Теперь документы и архивы стали электронными. Архив - это репозиторий, хранящийся на отдельном сервере. Чтобы получить актуальную версию документа не нужна никуда идти, - делаем запрос в репозиторий для получения последней версии электронного документа - pull. В документе уже есть все последние правки коллег.
Править полученный документ напрямую - это как дописывать в печатном документы между строчек. Делать так не будем. Вместо этого мы сделаем ксерокопии страниц, которые нас устраивают, а там где нужна правка перепечатаем и допечатаем страницы. В электронных документах стало проще - делаем собственную ветку (branch) и вносим правки в документ.
День окончен, - сдаём документ офис-менеджеру и получаем регистрацию в журнале учёта. Сейчас проще - отправляем commit, который фиксирует кто, когда, что и зачем исправил.
Каждый новый день всё повторяется: получаем документ, правим сдаём в архив. В какой-то момент мы понимаем, что документ готов и пора бы его отдать на согласование. Раньше через офис-менеджмент запускался процесс согласования - документ передавался специалисту, который будет передавать документ от одного согласующего к другому в соответствии с листом согласования. Сейчас проще - отправляем pull request в соответствии с настройками Git. Ответственный за согласование получают уведомление на электронную почту, согласовывают или возвращают с комментариями.
Если документ успешно прошёл весь путь по листу согласования, то офис менеджер подшивает утверждённую версию документа в архив. В цифровую эпоху это выполняется командой merge в основную ветку репозитория.
При размещении документа в архив ему присваивается новый номер. В Git для этого можно использовать расстановку тегов, которые будут отражать версию документа и позволит отделять рабочие версии от принятых.
Когда документ готов офис менеджер выполнит рассылку информации о выходе новой версии в соответствии с листом ознакомления. В случае использования Git это может быть настроено при выполнении ещё предыдущего пункта (автоматически при выставлении тега).
Почему docx плохо использовать с системами контроля версий?
Итак, процесс работы с документом мы автоматизировали и оцифровали. Теперь видно кто, когда и для чего вносил изменения, производятся автоматические рассылки, руководство может быть спокойно за то, что созданный в компании продукт хранится в одном месте и можно удобно делать его резервные копии. Но почему же все давно не перешли на такой вариант работы?
Наиболее распространённый формат, используемый для документов - Word. Файл docx для Git представляется как не читаемый бинарный файл. Git может видеть появление новых файлов, может понимать, что были внесены изменения в файл и кем, но содержательных изменений внутри файла не видит.

На рисунке видим, что Git нашёл новый файл; видит, что в первый файл внесены изменения, но показать что изменилось внутри файлов не может.
Остаются вопросы контроля работы аналитиков: чтобы увидеть изменения нужно скачать файл и сравнить с предыдущей версией, либо пользоваться функционалом Word, позволяющим отображать изменения, но тогда каждый день автор документа должен начинать с того, чтобы принять изменения и после этого вносить правки. Хотелось бы, чтобы система контроля версий также показывала изменения сразу и оставляла контроль изменений на своей стороне.
Кроме того, документы формата docx имеют плохую совместимость с AI. И если последние научились читать документы docx, то Word не умеет быстро и красиво вставлять ответы ИИ-помощников.
Умные чаты используют современный язык разметки - Markdown. Markdown (md) позволяет разметить текст так, чтобы он был удобно читаем и в то же время не изменяет его структуру, оставляя обычным текстовым документом, а не зашифрованным архивом. Поэтому md файлы удобно отслеживать в системах контроля версий.
Git отражает построчные изменения файлов md. Система контроля версий выделяет строки, в которых были внесены изменения и подсвечивает добавленный или исключённый текст.

В случае с md Git также обозначает какие файлы были добавлены, а какие - изменены. И также появляется возможность увидеть какие изменения внесены внутри файла. На примере выделено слово "плюсы" красным (исключено), а слово "преимущества" - зелёным (добавлено).
Md разметка добавляет в текст дополнительные спецсимволы, которые затрудняют немного чтение, однако сейчас появилось достаточное количество редакторов, позволяющих работать с Markdown файлами.
Репозиторий документации: структура и правила работы
Вместо docx+cloud предлагаю переходить на md+git.
Как будет выглядеть процесс написания технической документации?

MD-файлы обладают существенно меньшими возможностями для оформления документа. Некоторые привычные функции, доступные в Word, отсутствуют в Markdown. Эти недостатки компенсируются организационными изменениями в работе с MD-файлами. Например, Markdown не поддерживает автоматическое формирование оглавления, но его можно составить путём реорганизации хранения информации: один большой Word документ разбивается на структуру файлов и папок. В корневой папке создаётся индексный документ для размещения общей информации и скрипта, формирующего оглавление.
Чтобы наладить совместную работу, версионирование и получить другие преимущества работы с Git создаётся репозиторий, куда размещается система файлов и папок. Для внесения изменений автор создаёт ветку в репозитории, в рамках которой вносит изменения (в том числе создаёт новые файлы и папки). Каждый день по завершении работы аналитик фиксирует изменения в своей ветке (commit).
По завершении правок документ направляют на согласование - направляется запрос на проверку и включение изменений в основную ветку репозитория (pull request). Ответственный за репозиторий просматривает изменения в документе, может принять документ или отправить на доработку. Если не требуется внесение других доработок (например параллельных изменений не вносится), и документ решено принять, то для текущей версии документа устанавливается релизный тег с указанием версии документа. На это событие в Git можно настроить автоматические действия. Например, сборку pdf или docx версии документа (если уж без него никак), отправку уведомления списку ответственных лиц и тому подобное.
Преимущества использования Git в связке с Markdown
Подведём итог: какие преимущества предоставляет использование MD-файлов в связке с Git для ведения технической документации.
Во-первых, Git позволяет настроить документооборот: определить рецензентов, настроить лиц, которым отправляется рассылка, или даже реализовать более сложный документооборот с этапами.
Во-вторых, Git является системой контроля версий и при использовании текстовых документов, которыми являются MD-файлы, позволяет отражать изменения при каждом commit'е. Всегда можно найти состояние документа на ту или иную дату, когда и кем вносились изменения, сравнить с текущей версией - прозрачность и аудит.
В-третьих, Git позволяет автоматизировать процесс работы: отправку уведомлений ответственным, сборку финальной версии документа по событию и тому подобное. При этом проставленные теги выполняют фиксацию состояния документа, что позволяет просматривать документ той или иной версии - контроль версий и откат.
MD-файлы проще читаются AI помощниками. ИИ может формировать ответы в формате Markdown заметок, что упрощает работу авторов с документом. Это четвёртое преимущество - интеграция с ИИ.
В-пятых, регулярные commit'ы позволяют видеть ежедневные изменения и контролировать исполнение поставленных задач через встроенный механизм отслеживания изменений - ежедневный прогресс.
Ещё одним важным преимуществом является возможность легко указывать ссылки на документ при формировании задач на разработку, тестирование и тому подобное - можно указывать прямые ссылки на файлы не опасаясь, что ссылки станут недействительными.

Частые вопросы
Чем это лучше Confluence или Notion? Платформы дают вики и историю правок, но привязывают документацию к своему формату и тарифам. Markdown-репозиторий — ваш навсегда: обычные текстовые файлы, любой редактор, полная история в Git, офлайн-работа и свободная автоматизация через CI, возможность развернуть всё на собственных серверах.
Как быть с таблицами, диаграммами и картинками? Таблицы Markdown поддерживает, диаграммы удобно рисовать в Mermaid - это инструмент для создания диаграмм на основе текстового синтаксиса. Они тоже версионируются, есть встроенные в редакторы, которые работают с md.
Как быть, если процесс требует сборки единого документа? Финальные PDF и docx при необходимости собираются автоматически по тегу релиза в Git.
С чего начать, если уже есть множество документов в Word? Переходите на новые процесс постепенно: начните с «живых» документов, которые продолжают правиться. Архивные версии достаточно положить в репозиторий как есть — так сохранится история до перехода.
Сколько времени займёт переход? Начать можно за день: перенести один документ, настроить репозиторий и провести первую итерацию согласования. Команде без опыта с Git обычно хватает недели на привыкание. Безусловно переход потребует полноценного сопровождения изменений.