Сгенерированная документация терпит неудачу, когда модель определяет цели, гарантии или рекомендации для аудитории, которые никогда не указываются в репозитории. Рассматривайте каждое составленное предложение как утверждение, которое должно указывать на файл, тест или конфигурацию, которые уже содержатся в репозитории. Если п...
Сгенерированная документация терпит неудачу, когда модель определяет цели, гарантии или рекомендации для аудитории, которые никогда не указываются в репозитории. Рассматривайте каждое составленное предложение как утверждение, которое должно указывать на файл, тест или конфигурацию, которые уже содержатся в репозитории. Если путь отсутствует, предложение не является документацией; это спекуляция, которую следует исключить перед рассмотрением. В этой статье описывается экстрактивный рабочий процесс, который классифицирует утверждения, составляет только то, что может доказать дерево, и отклоняет остальное с помощью небольшого верификатора.
Этот метод предназначен для групп, которые уже генерируют фрагменты README, списки полей API или блоки команд Runbook из кода. Это не руководство по стилю и оно не оценивает качество письма. Он отвечает на более узкий вопрос: какие предложения может генерировать модель, а какими предложениями должен владеть человек, поскольку ни один файл не может их поддержать.
Почему экстрактивное составление лучше правдоподобной прозы
Черновики моделей часто кажутся законченными, потому что они дополняют недостающее намерение отраслевыми стандартами. Обработчик, возвращающий 409, становится «безопасным для повторных попыток». Флаг YAML становится «рекомендованным для производства». Эти предложения хорошо читаются в запросе на включение и терпят неудачу позже, когда операторы рассматривают их как контракт. Рецензенты, которые лишь бегло следят за тоном, упустят это из виду.