Экосистема технического письма

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Руководителю Аналитику Техническому писателю

Экосистема технического письма

Языки разметки

Современная техническая документация пишется в текстовых форматах с лёгкой разметкой — не в бинарных редакторах вроде 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’ы, что и код.

Плюс: полная прозрачность, контроль версий.

Минус: ограниченный функционал редактирования.

---