Ключевые принципы создания документации

Дата публикации: 2025-02-12

Термины

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

Введение

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

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

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

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

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

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

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

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

• Заголовок: 5–10 слов, максимум < 20
• Резюме: 30–50 слов, максимум < 150
• Введение: 10–20 слов, максимум < 50
• Обзор: 50–100 слов, максимум < 250
• Основной текст: 1000–3000 токенов, максимум < 8000 (токенайзер)

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

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

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

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