Архитектура документации

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

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

Архитектура документации

Архитектура документов

Архитектура документации — это целенаправленное проектирование структуры, содержания, форматов, потоков и взаимосвязей всех документов, сопровождающих продукт или систему на всех этапах её жизненного цикла. Она определяет - какие документы нужны, кто потребители, как документы связаны между собой, как организованы, как обновляются и поддерживаются.

Самая частая ошибка — рассматривать документацию как последствий разработки: «сделали — теперь напишем». Это приводит к запоздалому созданию, неполноте, несогласованности и быстрому устареванию. Но, как говорится, лучше поздно, чем никогда.

В идеале нужно создавать документацию параллельно с системой, с определением целевой аудитории, постановкой задач и метрик успеха, итерациями, ревью, тестированием, версионированием и поддержкой.

Проектирование архитектуры документации — это системный процесс. Он включает несколько этапов.

Определение аудитории (пользователей документации) - нужно понять, кто будет читать - разработчики, тестировщики, поддержка, заказчики - у каждой группы свои цели, уровень подготовки, контекст использования.
Картирование потребностей - нужно понять, что каждая история хочет узнать.
Определение типов документов - на основе потребностей формируется набор документационных артефактов - лучше сразу создать черновики - файлы или страницы в Confluence. Сразу всё - требования, проектирование, разработка, тестирование, эксплуатация, обучение.
Проектирование структуры и иерархии - ядро архитектуры, где нужно создать логическую, интуитивную систематизацию. Структура должна быть масштабируемой — новые модули, сервисы, интеграции не должны ломать её. Поэтому продумывать важно грамотно.

Как правильно структурировать?

Информация должна быть организована от общего к частному.

Пример:

Обзор системы → Модули → Сервисы → API → Методы → Параметры.

Иерархия снижает когнитивную нагрузку: пользователь «спускается» по уровням, как по ступеням. А чтобы удобно было спускаться - нужно позаботиться о навигации. Даже идеальная структура бесполезна без удобной навигации. Это меню, хлебные крошки, ссылки «назад/вперёд», карты сайта, перекрёстные ссылки между документами. Пользователь должен находить нужное не более чем за 3 клика.

Документы не должны существовать изолированно, нужно, чтобы были явные связи. Связность обеспечивает трассируемость и целостность знаний. Даже при идеальной структуре пользователи ищут через поиск. Он должен быть быстрым, релевантным, поддерживать синтаксис, фильтры, автодополнение, учитывать синонимы, опечатки, показывать контекст (куски текста, заголовки). Лучшие системы (например, Algolia, Elastic) индексируют текст и метаданные: теги, версии, владельцев.

Также важно отметить то, что любая документация так или иначе обрастает сленгом, поэтому нужен раздел «Термины и сокращения» или «Глоссарий», который бы выступил как справочник в виде таблицы с двумя столбцами - термин/сокращение, и определение (значение). Допустим, для новичка или пользователя привычные для вас термины могут быть неясными. Допустим, ТД это техническая документация, трудовой договор, так далее или ещё что-то?

Архитектура документации включает и форматы представления.

Разметка (markup). Разметка подразумевает использование специальной кодировки для подготовки грамотного форматирования текста. В базах знаний она встроенная. К примеру, Markdown самый лёгкий и читаемый формат, а reST чуть сложнее. А XML и вовсе страшный. В идеале, разметка должна быть единообразной и автоматизированной.
Метаданные - сведения об авторе, дата создания/обновления, версия, аудитория, статус (черновик, утверждён, архив), ссылки на требования, задачи, релизы. Метаданные позволяют автоматически генерировать оглавления, фильтровать по версиям, интегрировать с Jira, Git, CI/CD.

Управляется документация в течение всего своего жизненного цикла. Обычно этапы следующие:

Создание;
Ревью (техническое, стилистическое);
Утверждение;
Публикация;
Обновление;
Архивация.

Лучше всего интегрировать документацию в CI/CD-пайплайн.

Чего следует избегать при проектировании? Я бы выделил следующие антипаттерны.

Фрагментация — документы разбросаны: Confluence, Google Docs, email, PDF.
Отсутствие владельца — никто не отвечает за актуальность.
Избыточность — одна и та же информация в 5 местах.
Устаревание — никто не обновляет.
Отсутствие поиска — «найти нельзя, только перечитать всё».

Хорошая архитектура документации — признак зрелой инженерной культуры. Она показывает, что команда мыслит системно, уважает знания, строит продукт, а не просто код. Ха, но если есть желание что-то скрыть, то да, можно сделать её неудобной и адски бесконечной.

Элементы документа

+неразрывные пробелы и дефисы
+экспресс блоки
+перекрестные ссылки
+сквозная нумерация разделов, рисунков и таблиц

Из чего, собственно, состоит документ?

Начнём с иерархических единиц текста, которые формируют логическую структуру документа.

Главы редко встречаются, а в нормативке и вовсе отсутствуют. Это крупнейшая структурная единица документа, охватывает обширную тему, имеет собственный номер и может содержать разделы. Порой пункт может быть как раз главой, просто об этом явно не указывается.

Раздел - либо часть главы, либо всё же крупнейшая часть документа. Раздел всегда посвящается какой-то определённой теме, например «Функциональные требования». Нумеруется как пункт - 1, 2, 3. Если стоит ниже главы, то логично - 1.1, 1.2.

Подразделом называют некое уточнение раздела, «раздел в разделе». Соответственно, иерархически нумеруется как «номер родительского раздела.текущий номер» - подраздел 2 раздела 3 будет 3.2. Вложенность может быть какой угодно - хоть это будет даже 1.2.4.5.2.35.3.4.1.55.66 (ух, врагу не пожелаешь такой крупный документ читать).

Параграфом называют некую законченную мысль или правило в подразделе. В ГОСТах и юридических документах параграф — формальная единица (обозначается §), в технической документации термин часто используется как синоним абзаца.

Абзац — визуально выделенный фрагмент текста, начинающийся с отступа. Содержит одну основную мысль. Является минимальной смысловой единицей потока.

Документация грамотно оформляется с большими усилиями. Чтобы добиться красивого, отформатированного и оконченного варианта, приходится проходить ряд итераций согласования. И чтобы потом не проходить всё снова для нового документа, используются шаблоны.

Шаблон — это предопределённая структура документа, содержащая стандартные элементы: стили, заголовки, поля, колонтитулы, метаданные, оглавление. Шаблон обеспечивает единообразие оформления и сокращает время на создание.

Шаблоны могут быть реализованы в Word (.dotx), LaTeX, Markdown с YAML-фронтмэттером, или в системах вроде Confluence (page templates). Словом, чтобы человек мог скопировать и начать работу на готовом и согласованном варианте, откорректировав лишь то, что нужно. Это предотвращает «изобретение велосипеда», обеспечивает соответствие стандартам, упрощает ревью и публикацию.

В каждом документе могут быть стили и темы. Стили позволяют автоматизировать оформление; Темы — создать узнаваемый визуальный язык документации (например, корпоративный стиль).

Стиль — набор правил форматирования для определённого типа текста: шрифт, размер, межстрочный интервал, выравнивание, отступы. Например, стиль «Заголовок 1» — Arial 16pt, жирный, по центру.

Тема — совокупность стилей, цветов, шрифтов и эффектов, применяемых ко всему документу или набору документов для обеспечения визуального единства.

В тексте порой нужно прибегать к структурированию информации для более наглядного вида. Для этого используются списки и таблицы.

Список - это перечисление элементов. В основном их разделяют на иерархический, нумерованный и ненумерованный. Тут всё просто и наглядно:

это
нумерованный
список
- это
- ненумерованный
- список

а
1.	это
1.1.	список
1.1.1.	иерархический

Таблица же нам уже знакома. Это структура для представления данных в виде строк и столбцов. Позволяет компактно и наглядно сравнить параметры, перечислить значения, описать конфигурации. Пример: таблица с параметрами API-метода (параметр, тип, обязательный, описание). Это упорядочивает информацию, упрощает восприятие, особенно при работе с большими объёмами данных.

Когда глав много, требуется какой-то раздел, через который можно было бы быстро найти нужное место в тексте. Для этого существует оглавление.

Оглавление — список всех глав, разделов и подразделов документа с указанием страниц или якорей. Может быть ручным (составлен вручную, без автоматизации) или автоматическим (генерируется системой на основе стилей заголовков). Оно позволяет быстро ориентироваться в документе, переходить к нужному разделу (в электронной версии — по клику).

Чтобы оглавление автоматически заработало, нужно текст делить на заголовки с уровнями. Это можно сделать везде - в HTML, Word или Markdown. Заголовок 1 уровня обычно с крупным шрифтом, 2 уровня - меньше, 3 - ещё меньше.

Обычно их четыре.

Сноска — дополнительная информация, вынесенная за пределы основного текста. Она бывает:

Подстрочная — внизу страницы;
Концевая — в конце главы или документа.

Ссылка — указание на другой документ, веб-ресурс, раздел или источник.

Сноски позволяют сохранить читаемость текста, не перегружая его деталями; ссылки обеспечивают трассируемость и подтверждение информации.

Перекрёстная ссылка — ссылка на другой раздел, рисунок, таблицу или документ внутри текущего документа или в связанной документации.

Пример: «Подробнее о процессе см. в разделе 3.2» — при клике переходит к нужному месту. Это обеспечивает навигацию по документу, связывает темы, помогает избежать дублирования.

Сам текст в абзацах оформляется и выделяется специальными инструментами - отступы, интервалы, табуляция, блоки, спойлеры и форматирование кода.

Отступ — расстояние от края страницы до текста. Бывает: слева, справа, сверху, снизу.

Интервал — расстояние между строками (межстрочный) или абзацами (абзацный). Некоторые люди будут путать интервал и отступы, так что не теряйтесь.

Табуляция — горизонтальное смещение текста, задаваемое табуляторами (левый, центральный, правый, десятичный). Табуляция выравнивает текст по колонкам без таблиц.

Блок — выделенная область текста (часто с фоном, рамкой), содержащая особо важную информацию: примечание, предупреждение, совет.

Спойлер — скрытый блок, который можно раскрыть (в электронной документации). Используется для второстепенной или технической информации.

Форматирование кода — выделение фрагментов кода моноширинным шрифтом (например, git commit -m "fix"), часто с подсветкой синтаксиса. Это очень похоже на кавычки, но определяются символом «`».

Документы обсуждаются через примечания - это комментарий, оставленный в документе (в Word — через «Вставка → Примечание»). Может быть открытым или скрытым. В Word есть режим рецензирования - функция редактора, фиксирующая все изменения: добавления, удаления, перемещения. Позволяет видеть, кто что изменил и когда. Так делают ревью, работая над документом вместе.

Когда страниц много, в документах они должны нумероваться - тогда оглавление позволит перейти по номеру страницы.

Нумерация — присвоение порядковых номеров элементам документа (разделам, рисункам, таблицам, требованиям).

Виды нумерации:

Децимальная (иерархическая) — 1, 1.1, 1.1.1, 1.1.2 и т.д. Применяется для структурирования разделов, подразделов.
Квалификационная (классификационная) — номер содержит код, отражающий тип, категорию, принадлежность. Пример: REQ-001 (требование), TC-205 (тест-кейс), BUG-887 (баг). Такой номер несёт семантику: по префиксу понятно, что это за артефакт.
Сквозная нумерация — нумерация без привязки к иерархии: 1, 2, 3, 4… Используется, когда важен общий порядок (например, список требований в документе). Сквозная означает, что нумерация продолжается от начала до конца документа (или системы документов) без «сброса». Пример: в документе 150 требований — они нумеруются от REQ-001 до REQ-150, даже если распределены по разным главам.

Нумерация часто может быть в колонтитулах вверху или внизу.

Колонтитул — область в верхнем (верхний колонтитул) или нижнем (нижний колонтитул) поле страницы, повторяющаяся на каждой странице. Порой он содержит название документа, номер страницы, версию, дату, конфиденциальность. Это обеспечивает идентификацию документа, удобство при печати, соответствие стандартам.

Также можно разбавлять текст внешними элементами.

Фигура — графический элемент, сопровождаемый подписью (например, «Рисунок 1.1 — Архитектура системы»). Включает диаграммы, схемы, графики.

Значок (иконка) — маленький символ, передающий смысл (например, ⚠️ — предупреждение, 🔐 — безопасность).

Медиа — аудио, видео, анимации (редко в текстовых документах, но возможны в интерактивной документации).

Иллюстрация — любое изображение, поясняющее текст.

Скриншот — снимок экрана, демонстрирующий интерфейс, ошибку, настройку.

Визуализация ускоряет понимание, особенно сложных процессов. 90% информации в мозг приходит через зрение.

Когда речь идёт о печати документа, мы сталкиваемся с ещё двумя понятиями - ориентация и размер листа. Но и в электронном виде это влияет на читаемость, особенно при работе с графиками и таблицами.

Ориентация — положение страницы:

Книжная (портретная) — высота больше ширины, стандарт для текста.
Альбомная — ширина больше высоты, используется для широких таблиц, диаграмм.

Размер листа — физические габариты страницы: A4, A3, Letter и др.

Инструменты

Word — текстовый процессор, входящий в пакет Microsoft Office. Один из самых распространённых инструментов для создания технической документации, особенно в государственных и традиционных организациях. Мы его уже не раз упоминали и вы наверняка с ним знакомы. Именно этот инструмент используется для создания ТЗ, ПМИ, отчётов, инструкций, работы с шаблонами, совместного редактирования. Конечно тут есть автонумерация, экспорт в PDF, визуальное форматирование. В госсекторе и банках без этого никак.

Где есть Word, есть и Excel - табличный процессор, используемый для расчётов и как инструмент структурирования данных в документации. Это приложение для работы с таблицами, формулами, диаграммами. Часто используется как промежуточный формат или хранилище артефактов. Там бывают реестры требований, матрицы, планы, чек-листы, учёты ресурсов, метрик. Потому что он удобен для сортировки, фильтрации поиска и даже вычислений по формулам.

Однако есть важный момент. Excel не предназначен для написания текста, у него нет структуры, логика может размазаться. А Word не предназначен для кода - технические документы лучше передавать в классических текстовых файлах TXT или в Markdown.

Markdown — легковесный язык разметки, позволяющий форматировать текст с помощью простых символов. Это текстовый формат, в котором элементы (заголовки, списки, ссылки, код) обозначаются символами (#, -, ` и т.д.). Не требует специальных редакторов. В разметке Markdown всё просто - # для заголовков, - для списков, ``` для кода, ** для форматированного текста.

Эту разметку можно встретить почти везде - он поддерживает много всего, имеет мощную систему перекрёстных ссылок через [имястраницы] и интегрирован с автогенерацией.

# Глава 1
## Подраздел 1.1

См. [инструкцию](guide.md).

**Как используется**:
- Документация в Git-репозиториях (README.md);  
- Wiki (GitHub, GitLab, Bitbucket);  
- Генерация сайтов (через MkDocs, Jekyll, Hugo);  
- Совместная работа (текст в plain text, легко в Git).

LaTeX — система подготовки научных и технических документов, основанная на языке разметки. Это система, в которой текст описывается с помощью команд, а затем компилируется в PDF.

\section{Введение}
См. \autoref{sec:methods}.

\begin{lstlisting}[language=Python]
print("Hello")
\end{lstlisting}

Другой язык разметки - AsciiDoc, он позиционируется как альтернатива LaTeX и Word для технической документации. Это декларативный язык с богатыми возможностями: таблицы, макросы, атрибуты, темы, поддержка разных форматов вывода. Заголовки здесь через =, к примеру, поэтому синтаксис немного отличается.

= Документация
:doctype: book
:toc:

== Введение

См. xref:setup.adoc[Настройка].

DITA (Darwin Information Typing Architecture) - XML-ориентированная архитектура для создания, управления и публикации технической документации. Это стандарт OASIS, основанный на принципе модульности и повторного использования контента. Документы разбиваются на топики (concept, task, reference), которые можно комбинировать в разные сборки. Используется в крупных технических проектах, многоязычной документации, выпуске руководств, каталогов, инструкций.

<task id="install">
  <title>Установка</title>
  <taskbody>
    <steps>
      <step><cmd>Запустите установщик.</cmd></step>
    </steps>
  </taskbody>
</task>

Стили и секреты технического письма

Когда текст оформляется, он бывает в различных стилях, зависящих в первую очередь от своей задачи и целей, а также от аудитории, для кого он предназначен.

Я бы выделил три ключевых стиля технического письма:

Нормативно-юридический;
Технический научный;
Пользовательский.

Нормативно-юридический стиль — это стиль строгой, формализованной документации, в которой важны точность, однозначность и юридическая значимость. Он используется в документах, имеющих обязательную силу: регламенты, политики безопасности, стандарты, контракты, SLA, пользовательские соглашения (EULA), политики конфиденциальности и т.п.

Здесь обязательно:

Чёткая структура (разделы, подразделы, пункты, подпункты);
Использование нормативных формулировок (запрещается, обязан и тд);
Минимум эмоций, максимум точности;
Ссылки на нормативное обоснование (законы, ГОСТ, и иные документы);
Сложный язык, позволяющий избежать двусмысленности.

Собственно, двусмысленность здесь ключевое отличие, ведь нужно максимально однозначно указывать на что-то, с расчётом, что если пойти с этим документом в суд, то трактовка не будет использована против нас. Пример: «Пользователь не вправе передавать учётные данные третьим лицам. Нарушение данного положения влечёт приостановление доступа к системе.» Такой подход обязателен для политики информационной безопасности, договоров и соглашений, внутренних регламентов компании, и иных юридических документов. Чем меньше интерпретаций текста может быть - тем лучше. Даже если текст порой нечитабельный и «сухой», «холодный» и излишне подробный - это важно, так как нужно застраховаться от двойного толкования.

Технический научный стиль — это стиль, ориентированный на точное, логичное и объективное изложение информации. Он характерен для документации, адресованной специалистам: инженерам, разработчикам, архитекторам, аналитикам. Акцент делается на фактах, структуре, последовательности и доказательности.

Характерными чертами являются:

Использование терминологии, аббревиатур, схем, диаграмм;
Логическая структура: проблема - анализ - решение - обоснование;
Отсутствие эмоций, субъективных оценок;
Включение данных, расчётов, ссылок на исследования или бенчмарки (тесты);
Предложения сложные и информативные.

«Система использует шаблон CQRS для разделения потоков команд и запросов. Это позволяет достичь масштабируемости на уровне 10K RPS при задержке не более 50 мс в 99-м перцентиле. »

Такой текст сложный, но важен для понимания технологии - что пригодится учёным, исследователям, инженерам, аналитикам, разработчикам, архитекторам. Писать нужно так, будто читатель хочет повторить этот эксперимент. Каждое утверждение должно быть проверяемым, а решение обоснованным.

Это нужно применять в архитектурных решениях (ADR), технических спецификациях (SRS), исследованиях и научных статьях.

Пользовательский дружелюбный стиль — это стиль, ориентированный на удобство восприятия и понимания. Он используется в документации для конечных пользователей, новичков, нетехнических специалистов. Главная цель — помочь, а не впечатлить.

Характерные черты:

Простой, разговорный язык (но без сленга);
Короткие предложения;
Использование примеров, метафор, скриншотов;
Поддержка читателя «вот что сейчас увидите», «не волнуйтесь, это нормально»;
Акцент на действиях: «нажмите», «введите», «проверьте».

«Зайдите в настройки → выберите “Уведомления” → включите галочку “Оповещать о новых сообщениях”. Готово — теперь вы будете получать уведомления мгновенно!»

Использовать такой стиль нужно в руководствах, FAQ, подсказках, обучающих материалах и туториалах. Аудитория шире, и задача - помочь решить проблему без лишнего погружения.

Иногда один и тот же документ (например, API-документация) может сочетать технический научный стиль (для разработчиков) и пользовательский (в примерах и гайдах). А политика безопасности может быть написана в нормативном стиле, но дополнена пояснениями в дружелюбном тоне для сотрудников. Поэтому сочетание стилей может быть обосновано целью.

Во-первых, нужно писать для человека, а не для системы. Пользователю не нужно «понимать смысл» или «структуру», ему главное решить задачу. Каждый абзац должен отвечать на вопрос «Что мне с этим делать?».

Во-вторых, писать нужно с акцентом на количество лишних слов. Словом, убирать нужно всё, что не помогает пользователю сделать шаг. Не нужно описывать, что происходит «под капотом», если это не влияет на поведение пользователя. Он не должен «переваривать» архитектуру.

В-третьих, хорошая инструкция всегда содержит три элемента:

Контекст — зачем это нужно.
Действие — что делать.
Результат — что будет после.

«Чтобы получать уведомления о новых заказах (контекст), включите уведомления в настройках (действие). Вы будете получать оповещения на email и в приложении (результат).»

Бывают неоднозначные ситуации, и непонятно, когда умолчать, а когда погрузиться.

Если пользователь выполняет простую задачу (вход, сохранение) - умолчать, детали можно разместить по ссылке на отдельную статью или раздел, допустим «Как это работает».
Если ошибка или исключение - лучше погрузиться и объяснить, почему произошло и что делать.
Если настройка безопасности - объяснить риски, рассказав о последствиях.
Первое использование продукта - дать больше контекста, чтобы учить человека.

Главное - делать слоистую документацию, где основной путь простой, а глубокие детали - по ссылкам или в разделе «Подробнее».

А если же возникли сложности - использовать термин или простое слово, то нужно использовать «правило знакомства» - в первый раз объяснить термин простым языком, а после этого использовать термин смело. К примеру, в первый раз будет «API (интерфейс для обмена данными между программами) позволяет подключить ваш сайт к системе.», а дальше использование термина «Отправьте запрос к API, чтобы получить данные.».

Если аудитория - новички, лучше заменить всякие технические термины, что очевидно, к примеру, вместо «токен аутентификации» лучше «уникальный код доступа». Если термин не нужен пользователю для действия — не используйте его.

Когда без деталей не обойтись, используйте приёмы облегчения восприятия:

метафоры и аналогии;
пошаговые примеры;
визуализация (схемы, скриншоты, диаграммы);
разбивка на блоки - через заголовки и списки.

Одна из задач - преобразование текста из одного стиля в другой.

Технический научный в нормативно-юридический. Здесь нужно превратить описание в обязательное требование, и важно заменять или вовсе убирать неопределённость. Никаких сомнений, догадок или информации, которая может «подставить» в суде. Если что-то нужно сделать, лучше сразу указать «должен/не должен» или «обязан/не обязан». Если что-то можно сделать, но оно не обязательно, можно указать «вправе» или «имеет право», «имеет возможность».
Нормативно-юридический в технический научный. Здесь нужно превратить требование в реализуемое решение. К примеру, пришло требование от заказчика или переслали новый нормативный акт. При этом нужно раскрыть, как выполнить требования и расширить текст архитектурой, технологией и примерами. Допустим, если указано «Доступ к системе должен быть защищён двухфакторной аутентификацией.», значит нужно указать, какой именно подход двухфакторки был использован и добавить больше деталей.
Нормативно-юридический в пользовательский дружелюбный. Уже нужно объяснить правило так, чтобы пользователь понял, зачем и что делать. Убрать формальности, объяснить выгоду (если её нет, а обязанность есть - намекнуть, что обязательно), и дать простую инструкцию. Допустим, «Запрещается использование слабых паролей.» нужно будет обосновать, «Чтобы ваш аккаунт был в безопасности, придумайте надёжный пароль: минимум 8 символов, с цифрами и буквами. Например: Солнце2025! — и злоумышленникам будет сложнее взломать.».
Технический научный в пользовательский дружелюбный. Перевести нужно сложное в понятное, и не потерять суть. Термины лучше заменять на аналогии, если возможно, аббревиатуры объяснять. Нужно делать акцент на результате и на интерфейсе, который видит пользователь. Часто технический язык рассказывает «изнутри», а пользователь этого не видит.

Стиль

Техническая документация — это совокупность различных форм коммуникации, каждая из которых требует собственного стиля, тона и структуры. Выбор стиля определяется не личными предпочтениями автора, а характеристиками целевой аудитории, контекстом использования и целями документа. Ошибка в выборе стиля может свести на нет даже самую точную и полную информацию: формальный текст не поможет новичку, а разговорный тон в регламенте безопасности подорвёт его легитимность.

Существует три ключевых стиля технического письма, которые охватывают подавляющее большинство сценариев документирования в IT.

1. Нормативно-юридический стиль

Целевая аудитория: регуляторы, аудиторы, юристы, compliance-менеджеры, менеджеры по информационной безопасности.
Контекст применения: внутренние политики, регламенты, соглашения об уровне обслуживания (SLA), договоры, требования к защите персональных данных, стандарты соответствия (GDPR, ISO/IEC 27001, PCI DSS и др.).

Характеристики:

Язык строгий, без эмоциональной окраски.
Используются модальные глаголы с чёткой юридической нагрузкой: «должен», «обязан», «запрещено», «разрешается только при условии…».
Структура — нумерованные пункты, подпункты, чёткие ссылки на стандарты или внутренние документы.
Отсутствие примеров, метафор, интерактивности. Цель — не обучить, а зафиксировать обязательства и последствия их нарушения.

Пример:

«Доступ к производственной среде разрешён только после прохождения аутентификации с использованием двух факторов. Хранение учётных данных в открытом виде (plaintext) строго запрещено. Нарушение данного положения влечёт за собой отстранение от работы с системой и внутреннее расследование.»

Особенность: такой текст не предполагает интерпретации. Его читают для проверки соответствия. Поэтому важна точность и однозначность формулировок.

2. Технический научный стиль

Целевая аудитория: разработчики, системные архитекторы, инженеры по надёжности (SRE), технические лиды.
Контекст применения: спецификации API, архитектурные решения (ADR), технические RFC, внутренние отчёты об инцидентах, диаграммы компонентов, описания протоколов.

Характеристики:

Высокая плотность смысла: каждое слово несёт техническую нагрузку.
Использование точной терминологии, принятой в сообществе или внутри организации.
Минимум риторики, максимум логики: структура следует схеме проблема → анализ → решение → последствия.
Широкое использование формальных средств: код, схемы (UML, C4, Sequence Diagrams), таблицы параметров, математические или логические выражения.

Пример:

«Сервис реализует паттерн event sourcing. Все изменения состояния записываются как события в Apache Kafka с топиком user.events. События сериализуются в формате Avro с использованием схемы, зарегистрированной в Confluent Schema Registry (версия 3.2). Потребители должны соблюдать обратную совместимость при десериализации.»

Особенность: читатель обладает высокой квалификацией и ожидает, что автор не будет «разжёвывать» базовые понятия. Однако ожидается полнота технических деталей, необходимых для воспроизведения или диагностики.

3. Пользовательский дружелюбный стиль

Целевая аудитория: новые разработчики, нетехнические пользователи (продуктовые менеджеры, аналитики), внешние интеграторы, клиенты.
Контекст применения: руководства быстрого старта (Quick Start), пошаговые туториалы, FAQ, интерактивные гайды, документация SDK.

Характеристики:

Простой, доступный язык. Жаргон либо отсутствует, либо сразу поясняется.
Акцент на действиях: «сделайте это», «нажмите сюда», «получите такой результат».
Использование примеров, скриншотов, анимаций, сценариев использования.
Дружелюбный, поддерживающий тон: «Давайте попробуем», «Вы увидите следующее», «Не волнуйтесь, это нормально».
Пошаговость и предсказуемость: читатель должен знать, что делать дальше, на каждом этапе.

Пример:

«Начнём с установки! Откройте терминал и выполните:
npm install @myorg/sdk
После этого вы сможете создать клиента одной строкой:
const client = new MySDK({ apiKey: 'ваш_ключ' });
Готово! Теперь вы подключены.»

Особенность: цель — снизить порог входа и вызвать доверие. Пользователь должен чувствовать, что система «думает за него» и помогает, а не требует от него усилий по расшифровке.