Документация обновляется вместе с задачей

Правило

Документация — часть definition of done, а не отдельная задача «потом». Если изменение затронуло строку из левой колонки — правая обновляется в той же задаче, и ревьюер это проверяет:

Что меняем	Что обновляем
Интеграцию (контракт, точки входа, расписание)	Паспорт интеграции
Внешнюю обработку / отчёт / ВПФ	Карточку: Информация и Версия в СведенияОВнешнейОбработке() + строка «что изменилось»
Регламентное задание (новое, расписание, смысл)	Реестр регламентных заданий
Экспортный метод программного интерфейса	Комментарий-описание: назначение, параметры, возвращаемое значение
Роли и права	Описание профилей: кому какой профиль выдаётся и почему
Поведение, заметное пользователю	Инструкцию или памятку «что изменилось»
Архитектурное решение с долгосрочными последствиями	ADR-запись
Состав баз и правила контуров	Описание контуров

Для экспортных методов в области ПрограммныйИнтерфейс описание обязательно — это же проверяют диагностики PublicMethodsDescription, MissingParameterDescription, MissingReturnedValueDescription.

Зачем

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

Неправильно

// Ни назначения, ни параметров, ни того, что будет при ошибке.
// Вызывающий узнает семантику ТолькоПроведенные методом проб.
Функция ПолучитьЗаказыКОтгрузке(Склад, ТолькоПроведенные = Истина) Экспорт
    // ...
КонецФункции

Правильно

// Возвращает заказы, готовые к отгрузке с указанного склада.
//
// Параметры:
//  Склад - СправочникСсылка.Склады - склад отгрузки.
//  ТолькоПроведенные - Булево - Истина (по умолчанию) — только проведённые
//      заказы; Ложь — включая черновики (для предварительного плана).
//
// Возвращаемое значение:
//  Массив из ДокументСсылка.ЗаказКлиента - пустой массив, если заказов нет.
//
Функция ПолучитьЗаказыКОтгрузке(Склад, ТолькоПроведенные = Истина) Экспорт
    // ...
КонецФункции

Когда не применять

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

См. также

• ADR — записи архитектурных решений
• Интерфейсные тексты через НСтр
• Исходники в git, линт и quality gate как условие мерджа
• Код-стайл: корпоративные дополнения
• Контуры баз — прод, тест, копии
• Обработка ошибок и логирование
• Общие модули и слои — где живёт логика
• Паттерны работы с БСП (вход, профили доступа, допреквизиты)
• Паттерны СКД (галочка-отбор, заголовок поля внешнего набора)
• Ревью и шаблон описания изменения
• Секреты в безопасном хранилище; техпользователь с минимальными правами
• Структура модуля и областей

• Паспорт интеграции — обязательная документация
• Шаблон описания изменения (MR)
• Внешние отчёты и обработки — подключение через БСП