Лучший способ управления документацией в 2027 году
Документация является частью проекта, который каждый согласен с вопросами, и никто не согласен с тем, как работать. Посмотрите на пять проектов с открытым
Документация является частью проекта, который каждый согласен с вопросами, и никто не согласен с тем, как работать. Посмотрите на пять проектов с открытым исходным кодом и вы найдете пять различных настроек. Некоторые хорошо работают. Большая часть дрейфует в пренебрежение.
Вот как на деле выглядят общие шаблоны на практике, и почему некоторые держатся лучше, чем другие.
Вики-подход: быстрый старт, медленно и
GitHub wikis и Confluence являются по умолчанию для многих команд. Они быстро настроены, конфигурация не требуется, и любой может добавить страницу.
Проблема в том, что wikis накапливает страницы быстрее, чем они поддерживаются. В рамках двухлетнего проекта место для участия в нем обычно имеет точные страницы, устаревших страниц, и нет надежного способа сказать, какой именно из них. Искать все одинаково поверхности. Нет процесса проверки. Никто не имеет ничего.
GitHub wikis имеет такую же проблему с дополнительными ограничениями: они живут в отдельном хранилище от вашего кода. Pull Request'а, который меняет API, не побуждает никого обновлять документы. Разрыв между кодом и документированием незаметно расширяется.
Команды, которые используют wikis, являются исключением. Обычно у них есть специализированный технический писатель, обеспечивающий соблюдение стандартов. Большинство команд не было.
Понятие и аналогичные инструменты: отлично подходит для внутренних команд, плохо для долголетия
Notion - это действительно хорошая для внутренней документации — инструкции, сборки, командные процессы, записки о встрече. Редактор гибкий, разрешений является гранулированным, и он достаточно прост в использовании, что не технические разработчики действительно используют его.
Для документации по проекту, предназначенной для того, чтобы жить вместе с кодом, он будет сокращен несколькими способами.
Ваши документы находятся в базе данных Notion, а не в вашем репозитории. Нет различий, нет обзора PR автоматического развертывания. Если Notion изменяет цены, устаревает функция или просто исчезает, миграция является ручной работой по экспорту и переформатированию.
Более глубокая проблема - это открытие. Доски, которые живут в Нотации не индексируются вместе с вашей базой кода. Приветствие разработчика для имени функции не найдено на странице Notion, которая объясняет, почему она работает так, как это делает. Две системы не общаются друг с другом.
Ориентирован на README: честно, но трудно масштабировать
Множество небольших проектов — и многие из них с открытым исходным кодом — почти полностью полагаются на README. Один файл, содержащий текущий, охватывающий рекомендации по установке, использованию и внесению взносов.
Это удивительно хорошо работает для сфокусированных инструментов с стабильным API. Ограничение приоритизации для одного файла. Нет распыления документации, потому что нет места для этого.
Это разрушается, когда проект становится все более сложным. README, который охватывает пятнадцать различных вариантов конфигурации, три цели развертывания и руководство по миграции от v1 к v2 останавливается для чтения. На этом этапе команды либо позволяют вращаться, либо начать строить что-то еще.
Док-код: шаблон, масштабирующий
Проекты с неизменно хорошей документацией используют тот же базовый шаблон: Markdown файлы в хранилище, построен статическим генератором сайта, развернутым вместе с каждым релизом.
Документы Kubernetes находятся в том же монорепо, что и кодовая база, проверенные в том же рабочем потоке pull request. Rust Book - это проект Markdown на GitHub с сотнями участников. Документация Astro's это сайт Astro Starlight, созданный вместе с самой фреймворком.
То, что делает эту работу не инструментальной. Это рабочий процесс. Работает в режиме реального времени рядом с кодом, поэтому при изменении кода они получают обновления. PR добавляет новый флаг для обновления документации, прежде чем он будет объединен. Процесс обзора обеспечивает его осуществление.
Вторичное пособие - долговечность. Markdown файлы с 2015 до сих пор читаются и устанавливаются в 2027 году. Миграция не требуется, проприетарный экспорт не зависит от платформы. Содержимое является текстовыми файлами в папке.
Трение убийств, которое служит кодом для нетехнических помощников
Одна реальная слабость подхода Markdown-in-Git заключается в том, что он предполагает, что все удобно с текстовым редактором и pull-запросом. Для многих команд это хорошо. Для команд с нетехническими вкладчиками — маркетинг, продукт, поддержка — это создает трение, которое приводит к игнорированию документации или поддержке в параллельной системе.
В этом случае CMS с поддержкой Git. Инструменты, такие как LightCMS находятся перед хранилищем и дают авторам реальный редактор, сохраняя файлы Markdown в репозитории. Редактор обрабатывает форматирование. CMS обрабатывает фиксацию. Участник конкурса никогда не видит терминала.
Результат такой же, как и документ как код — содержимое в Markdown, версия в Git, развернут вашей существующей трубопроводом — но доступны людям, которые не хотят использовать Git напрямую.
Что на самом деле работает в 2027 году
Содержимый шаблон прост: Markdown файлы в вашем хранилище, собранные генератором статических сайтов, рассмотрены в pull-запросах, развернутых на слиянии.
Конкретные инструменты вокруг этого шаблона имеют значение меньше, чем рабочий процесс. Если ваша команда использует GitHub, сайт Starlight или Docusaurus, созданный для того же репозитория, дает вам все: поиск, версия, соответствующий опыт чтения и процесс проверки, который позволяет синхронизировать документы с кодом.
Если у вас есть нетехнические авторы, поместите перед ним редактор, поддерживаемый Git, чтобы они могли писать без соприкосновения с терминалом. Современная настройка остается прежней. Содержимое остается в вашем репозитории.
Проекты с лучшей документацией не являются лучшими инструментами. Они составляют часть документации того же рабочего процесса, что и код.
ЧАВО
Что такое документация как код?
Docs-as-code - это практика написания и сопровождения документации с использованием тех же инструментов и рабочих процессов, что и разработка программного обеспечения: обычные текстовые файлы (обычно Markdown), контроль версий (обычно Git), проверка кода и автоматическое развертывание. Она держит документацию рядом с кодом, который она описывает, и делает обновления частью нормального рабочего процесса разработки.
Является ли Markdown Good Enough для документации?
Да, для подавляющего большинства проектов. Markdown обрабатывает заголовки, блоки кода, таблицы, изображения и ссылки. Статические генераторы сайтов, такие как Starlight, Docusaurus и MkDocs добавляют поиск, навигацию, версию и хороший опыт чтения сверху. Ограничение простого текста является особенностью: он читается в любом редакторе, гребном, диффузном и долговечном течение десятилетий.
How Do Non-Technical Writers Contribute to Markdown Documentation?
Полученные от GMS инструменты типа LightCMS предоставляют богатый редактор, который фиксирует Markdown в ваш репозиторий и не требует от авторов использовать Git напрямую. Содержимое остается в вашем репозитории в обычном Markdown. Редактор просто является более доступным интерфейсом к тем же файлам, которые лежат в его основе.
Что такое лучший статический генератор сайта для документации?
Зависит от вашего стека. Astro Starlight и Docusaurus являются самыми полнофункциональными вариантами с хорошим поиском из коробки. MkDocs с Material отлично подходит для проектов Python. Если вы уже на Hugo или Eleventy для вашего блога, они также могут обрабатывать документы. Генератор имеет значение, чем хранить документы в том же репозитории, что и ваш код.