Перейти к основному содержимому

Правила Написания Документации

Назначение​

Этот документ задает общий корпоративный стандарт для всей документации Pin. Он определяет, как проектировать структуру документации, как избегать дублирования правил и как поддерживать единый source of truth между файлами.

Базовые Правила​

  • Документация пишется на русском языке и хранится в UTF-8.
  • Английские слова допустимы только как технические идентификаторы.
  • Документ должен быть пригоден для чтения без устных пояснений.
  • Обзорный файл не подменяет детальные спецификации.
  • Если код и документация расходятся, задача по изменению считается незавершенной.

Централизация Общих Требований​

Повторяющиеся требования не копируются заново в каждый документ. Вместо этого:

  • общие metadata/security/observability/compatibility требования хранятся в Общих Требованиях К Документам;
  • общие Definition Of Ready и Definition Of Done хранятся в Definition Of Ready И Definition Of Done;
  • специализированные правила, например по DDD и rich model, хранятся в отдельных нормативных файлах и переиспользуются через ссылки.

Если документу нужны дополнительные правила, он должен добавлять только domain-specific уточнения сверх общего стандарта.

Правила Структуры​

  • Один файл отвечает за одну тему.
  • Документ длиннее 250 строк или примерно 12 KB должен быть кандидатом на разбиение.
  • Большой раздел дробится на папку с README.md и детальными файлами.
  • Имена файлов пишутся в kebab-case.
  • Внутри одного раздела документы используют единый порядок секций.

Source Of Truth И Ссылки​

  • Документ обязан ссылаться на upstream source of truth, если зависит от другого контракта, ADR, правила или шаблона.
  • Системные документы не должны вводить новый runtime contract без ссылки на детальный файл контракта.
  • Общие правила должны жить в одном нормативном файле и использоваться по ссылке.
  • Копирование текста вместо ссылки допускается только если документ теряет самостоятельность без краткого локального пояснения.

Требования К Стилю​

  • Пиши конкретное бизнес-поведение и контрактные имена — сущности, поля, статусы, enum, коды ошибок, топики, события, а не имена классов, хендлеров, валидаторов или типов SDK. Указывай: какие поля читаются, какие меняются, какие статусы возможны, какие события публикуются.
  • Избегай размытых слов вроде обработать, проверить, обновить, выполнить, если за ними не перечислено точное поведение.
  • Не смешивай бизнес-описание, архитектурное решение и task-level детали в одном абзаце.
  • Спецификация-постановка ссылается на контракты (сущности, события, соседние операции), а не на файлы правил авторинга и не на конкретные файлы реализации.
  • Используй таблицы там, где есть перечислимые правила, поля, статусы, approvals и controls.

Что Должно Быть Вынесено В Общие Файлы​

В отдельные нормативные документы выносятся:

  • правила оформления metadata;
  • общие требования к typed models;
  • cross-cutting security requirements;
  • observability minimum;
  • compatibility and migration rules;
  • общие DoR/DoD;
  • переиспользуемые engineering rules вроде DDD/rich model, transaction boundaries, naming standards.

Минимальная Проверка Перед Commit​

  • документ в UTF-8 и без битой кодировки;
  • неприменимые секции опускаются целиком, а не помечаются not applicable; оставшиеся placeholders <...> заменены;
  • терминология согласована с соседними разделами;
  • таблицы полей заполнены там, где они обязательны;
  • указаны owner, dependencies, risks и related docs;
  • ссылки ведут на актуальные документы;
  • локальный документ не дублирует без необходимости большой кусок общего нормативного текста.

Обратные ссылки​

Автоссылки: где используется этот документ.