Экосистема технического письма
Экосистема технического письма
Языки разметки
Современная техническая документация пишется в текстовых форматах с лёгкой разметкой — не в бинарных редакторах вроде Microsoft Word. Это позволяет хранить документацию в системах контроля версий, интегрировать её в CI/CD и обрабатывать автоматически.
Markdown
— Стандарт де-факто для большинства IT-проектов.
Даже Вселенная IT использует Markdown.
Простой, читаемый даже в исходном виде, идеально подходит для README, wiki, блогов и внутренних гайдов.
Варианты:
- CommonMark — строгая спецификация, обеспечивающая совместимость между парсерами.
- GitHub Flavored Markdown (GFM) — расширение с поддержкой таблиц, задач (
- [x]), автоссылок на issue и код. - Markdown Extra — используется в некоторых генераторах (например, в MkDocs) для расширенных возможностей.
reStructuredText (reST)
— Инструмент Python-сообщества и основа Sphinx.
Более выразителен, чем Markdown: поддерживает условные блоки, сложные перекрёстные ссылки, автоматические оглавления и глубокую интеграцию с кодом.
Используется в официальной документации Python, Django, Read the Docs.
AsciiDoc
— Мощная альтернатива для масштабных проектов.
Поддерживает сложную структуру, включение внешних файлов, переменные, условную компиляцию.
Генерирует HTML, PDF, EPUB, man-страницы. Используется в документации Red Hat, Kubernetes (ранние версии).
DITA (Darwin Information Typing Architecture)
— Enterprise-стандарт на базе XML.
Позволяет создавать модульную, многоканальную, локализуемую документацию.
Контент разбивается на «темы» (концепции, задачи, справочники), которые можно повторно использовать в разных сборках.
Широко применяется в авиации, медицине, промышленном ПО, где требуется строгая трассируемость и соответствие стандартам.
DocBook
— Классический XML-формат для технических книг и стандартов.
Старше DITA, но по-прежнему используется в академической и регуляторной документации.
Поддерживает сложную структуру: главы, разделы, библиографии, глоссарии.
Выбор языка разметки зависит от:
- масштаба проекта (личный блог vs регулируемая индустрия),
- требований к повторному использованию,
- интеграции с существующей инфраструктурой,
- аудитории (разработчики предпочитают Markdown, инженеры — AsciiDoc).
Инструменты
Язык разметки — только основа. Чтобы превратить текст в интерактивный сайт, PDF или API-портал, нужны генераторы и системы публикации.
MkDocs
— Простой, быстрый генератор на основе Markdown.
Идеален для небольших и средних проектов. Поддерживает темы (Material for MkDocs), поиск, плагины.
Интегрируется с GitHub Pages, GitLab CI, Read the Docs.
Sphinx
— Мощная система, изначально созданная для документации Python.
Работает с reST, но поддерживает и Markdown через расширения.
Автоматически генерирует API-документацию из кода (через autodoc), поддерживает математические формулы (LaTeX), глоссарии, многоязычность.
Стандарт для научных и инженерных проектов.
Docusaurus
— Современный генератор от Meta (Facebook), построенный на React.
Кстати, Вселенная IT использует Docusaurus.
Оптимизирован для open source: поддержка версионирования документации, локализация, блог, search через Algolia.
Идеален для проектов с большой внешней аудиторией (например, библиотек, фреймворков).
GitBook
— Комбинация редактора и хостинга.
Удобен для внутренней документации, учебных курсов, продуктовых гайдов.
Менее гибок для сложных интеграций, но требует минимум настройки.
LaTeX
— Не инструмент для повседневной документации, но незаменим для научных, академических и формальных текстов.
Позволяет верстать сложные документы с формулами, теоремами, перекрёстными ссылками, библиографиями.
Используется в математике, физике, теоретической информатике.
Obsidian
— Локальное приложение для создания «персональной вики».
На основе Markdown с поддержкой внутренних ссылок, графа знаний, шаблонов.
Отлично подходит для черновиков, ADR, личных заметок и систематизации знаний перед публикацией.
Также отличное решение для построения своих локальных баз знаний на Markdown.
Форматы спецификаций
Современная документация часто существует как машиночитаемый формат, который можно использовать для генерации, тестирования и интеграции.
OpenAPI (Swagger)
— Стандарт описания RESTful API.
Описывает endpoint’ы, параметры, тела запросов/ответов, схемы данных, коды ошибок в YAML или JSON.
Из одного файла можно:
- сгенерировать интерактивную документацию (Swagger UI),
- создать клиентские SDK,
- запустить mock-сервер,
- проверить соответствие реализации спецификации.
AsyncAPI
— Аналог OpenAPI для event-driven систем (Kafka, RabbitMQ, AWS SNS/SQS).
Описывает каналы, сообщения, схемы, протоколы.
Позволяет автоматизировать документирование микросервисов, обменивающихся событиями.
Pandoc
— «Универсальный конвертер» текстовых форматов.
Поддерживает более 50 входных и выходных форматов: Markdown → PDF (через LaTeX), reST → HTML, DOCX → Markdown и т.д.
Незаменим при необходимости публикации в нескольких каналах: веб, печать, электронная книга.
Системы хранения и совместной работы
Где живёт документация — определяет её судьбу. Слишком централизованная система тормозит обновление, слишком децентрализованная — ведёт к фрагментации.
Confluence
— Корпоративный стандарт для многих компаний.
Мощный редактор, права доступа, интеграция с Jira.
Риск: без чёткой архитектуры превращается в «кладбище страниц», где ничего нельзя найти.
Notion
— Гибкая, визуально привлекательная платформа.
Хорошо подходит для стартапов и небольших команд.
Ограничение: закрытая экосистема, сложная интеграция с Git, отсутствие версионирования.
Read the Docs
— Хостинг для документации с автоматической сборкой из Git.
Поддерживает Sphinx и MkDocs, версионирование, поиск, локализацию.
Стандарт для open source проектов.
GitHub/GitLab Wiki
— Простое решение, где документация хранится рядом с кодом.
Редактируется через те же pull request’ы, что и код.
Плюс: полная прозрачность, контроль версий.
Минус: ограниченный функционал редактирования.