# Принципы подготовки документации

- Использовать официально-деловой стиль, избегать разговорных и жаргонных формулировок.
- Не включать примеры кода, в том числе фрагменты конфигураций или скриптов; описывать действия словами.
- Организовывать материалы в отдельных файлах для ключевых областей (например, обзор, развертывание, API, процессы сопровождения) и поддерживать единый формат заголовков.
- Обновлять соответствующие разделы при изменениях функциональности, зависимостей или интерфейсов API.
- Поддерживать терминологическую согласованность: использовать единые названия сущностей, статусов и ролей по всему комплекту документов.
- Фиксировать требования к окружению и предпосылки перед инструкциями, чтобы читатель мог заранее подготовиться.
- Добавлять краткие вводные разделы, описывающие цель документа и ожидаемый результат выполнения шагов.
- Проверять инструкции на полноту: для каждого процесса указывать входные данные, последовательность действий и критерии успешности без демонстрационных примеров.
- Для API описывать назначение методов, входные и выходные данные, возможные ошибки и форматы ответа без приведения структур в виде кода.
- При изменении структуры документации актуализировать перекрестные ссылки между файлами, чтобы обеспечить целостность навигации.
- Приводить обязательные зависимости и связанные конфигурационные файлы в каждом разделе, если без них невозможно выполнить описанную операцию.
- Согласовывать формат дат, единиц измерения и терминов, избегая смешения языка оригинала и транслитерации.
