Статьи с меткой: Инструменты
Sphinx, MkDocs, Astro и другие генераторы оптимизированы под разные модели контента и команды. Сравнивайте авторский процесс, расширяемость, локализацию и стоимость сопровождения, а не красоту демо и длину списка функций. Демо генератора может выглядеть великолепно и при этом не подходить вашей документации.
Поиск по документации нужно выбирать и настраивать вокруг запросов, которые пользователь не может разрешить, а не вокруг длинного списка функций поставщика. Поиск особенно полезен, когда читатель знает термин или симптом, но не знает, где лежит информация.
Диаграммы, заданные текстом, удобно сопровождать и проверять, но только если визуальная задача соответствует тому, что выбранная нотация умеет выражать понятно. Диаграммы как код хорошо подходят для потоков, состояний, зависимостей и последовательностей, где главное — связи.
Форматы и конвейеры публикации поменялись радикально, но долговечные проблемы знакомы: контроль источника, reuse, навигация, ревью и синхронизация опубликованной информации с продуктом. Задолго до термина Docs-as-Code команды боролись с несколькими копиями исходников, повторно используемыми фрагментами, версиями руководств и вопросом, какая копия актуальна.
Относитесь к документации как к сборочному артефакту: проверяйте структуру, ссылки, примеры и правила публикации до того, как изменения увидят читатели. CI не решит, полезно ли объяснение читателю, но способен отсеять множество предсказуемых дефектов до того, как на них потратит время человек.
Markdown остаётся простым только тогда, когда команда заранее договорилась о структуре, метаданных и расширениях, пока тысячи файлов не сделали каждое исключение вечным. Заранее стандартизируйте имена файлов, frontmatter, заголовки, изображения и внутренние ссылки.
Линтинг стиля полезен, когда ловит расползание терминологии, рискованные формулировки и повторяемые редакционные дефекты. Держите набор правил небольшим, объяснимым и достаточно тихим, чтобы авторы доверяли падению проверки. Линтер способен проверить тысячи предложений за секунды, поэтому хочется закодировать в нём каждое редакционное предпочтение.
Офлайн-документация заставляла иначе думать о версиях, поиске, упаковке и цене ошибки, которую нельзя было исправить сразу после релиза. Физическая граница публикации делала заморозку контента, проверку сборки и релизную координацию особенно заметными.