Экосистема технического письма
ERD и словарь сущностей — Entity Relationship, нормализация, SQL. Карта — о разделе.
Экосистема технического письма
Языки разметки
Современная техническая документация пишется в текстовых форматах с лёгкой разметкой — не в бинарных редакторах вроде Microsoft Word. Это позволяет хранить документацию в системах контроля версий, интегрировать её в CI/CD и обрабатывать автоматически.
Markdown
— Стандарт де-факто для большинства IT-проектов.
Даже Вселенная IT использует Markdown.
Простой, читаемый даже в исходном виде, идеально подходит для README, wiki, блогов и внутренних гайдов.
Если команда только начинает системно писать документацию, Markdown почти всегда лучший старт — низкий порог входа, прозрачный diff в Git, простое ревью через pull request.
Варианты:
- 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
— Не инструмент для повседневной документации, но незаменим для научных, академических и формальных текстов.
Позволяет верстать сложные документы с формулами, теоремами, перекрёстными ссылками, библиографиями.
Используется в математике, физике, теоретической информатике.
Готовые фрагменты для лабораторных и курсовых — LaTeX — формулы для отчётов; графики для вставки в PDF — Matplotlib — графики. Символьные расчёты и экспорт формулы — SymPy — уравнения и производные.
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’ы, что и код.
Плюс: полная прозрачность, контроль версий.
Минус: ограниченный функционал редактирования.
Как выбрать стек документации на практике
Быстрый ориентир:
- Маленькая команда, быстрые изменения, нужен минимум бюрократии -> Markdown + GitHub/GitLab + простой генератор.
- Большая продуктовая документация для внешних разработчиков -> Docusaurus или аналог с версионированием.
- Корпоративная среда с активной бизнес-аудиторией -> Confluence/Notion + четкие правила структуры.
- Регулируемая отрасль и строгая трассируемость -> DITA/DocBook или гибрид с формальными шаблонами.
Выбор зависит от размера команды, аудитории и требований к версионированию.
Минимальный roadmap внедрения экосистемы
- Шаг 1: определить владельцев документации по доменам.
- Шаг 2: зафиксировать шаблоны страниц и правила ссылок.
- Шаг 3: включить проверку ссылок и сборку документации в CI.
- Шаг 4: добавить метрики качества и актуальности.
- Шаг 5: раз в месяц проводить ревизию "мертвых" и дублирующих материалов.
Эти шаги напрямую связаны с соседними темами: