---
title: "Ключевые принципы создания документации"
date: 2025-02-12
---

<zoom-img
            src="/img/brand/doc.svg"
            alt="Ключевые принципы создания документации"
            width="100px"
            style="float: left; margin: 15px 15px 0 0;"
    ></zoom-img>

## Термины

- **Аудитория документации** — группа людей и/или языковых моделей
  (LLM), которые используют документацию для формирования когнитивного
  контекста. Включает конечных пользователей, разработчиков, аналитиков
  и других заинтересованных лиц.
- **Когнитивный контекст** — совокупность знаний, опыта, ожиданий и
  мотивации, определяющая восприятие и интерпретацию информации.
  Включает как предшествующие знания, так и текущие цели.
- **Объект документации** — продукт, процесс или концепция, описываемая
  в документе: ПО, методология, бизнес-процесс и т.д.

## Введение

Документация — это процесс синхронизации когнитивного контекста
аудитории (людей и LLM). Цель — обеспечить целостное понимание
описываемого объекта, начиная с общих понятий и переходя к деталям.
Информация представляется иерархически, без дублирования, позволяя как
бегло ознакомиться, так и углубиться.

## Погружение читателя в контекст

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

## Иерархия и структура

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

### Уровни документации

- **Заголовок** — краткое название, отражающее суть.
- **Резюме** — очень краткое описание смысла (ментальный якорь).
- **Введение** — цель документа, его аудитория, установка контекста.
- **Обзор** — краткое изложение, позволяющее оценить релевантность.
- **Основной раздел** — детальное описание, структурированное по
  предметной области.

### Рекомендации по объёму

- Заголовок: 5–10 слов, максимум \< 20
- Резюме: 30–50 слов, максимум \< 150
- Введение: 10–20 слов, максимум \< 50
- Обзор: 50–100 слов, максимум \< 250
- Основной текст: 1000–3000 токенов, максимум \< 8000
  (<a href="https://platform.openai.com/tokenizer"
  target="_blank">токенайзер</a>)

## Навигационная доступность

Документация — это взаимосвязанная структура, где каждый документ
охватывает один аспект. Гиперссылки, оглавления и перекрёстные ссылки
должны помогать навигации. Читатель всегда должен понимать своё
положение в структуре и иметь возможность перейти к связанным темам или
вернуться к обзору.

## Ориентация на LLM

Документация должна учитывать особенности работы языковых моделей и
оформляться в Markdown. Ключевая информация — в начале секций. Важно
использовать единообразную терминологию, избегать неоднозначности.
Структура — логичная, иерархическая, с чёткой разметкой заголовков и
списков. Разделы должны быть самодостаточными, но взаимосвязанными.