Docs as Code – Code as Docs – No Docs
Краткое резюме
В статье рассматриваются подходы к оптимизации технической документации: Docs as Code для требований к системе, Code as Docs для описания состояния системы и No Docs для минимизации пользовательской документации через понятные интерфейсы и встроенные подсказки.
Основные проблемы, связанные с технической документацией, заключаются в её отсутствии или неактуальности.
Рассмотрим, как можно оптимизировать процесс создания технической документации и повысить её качество и актуальность.
Техническая документация выполняет три основные функции:
1. Описание требований к системе и принятых решений.
2. Представление текущего состояния системы.
3. Инструктаж пользователя по работе с системой (развёртыванию и эксплуатации).
Первый вид документации — требования к системе. В условиях использования больших языковых моделей, кодогенерации и декларативного подхода к описанию инфраструктуры требования должны быть сформулированы таким образом, чтобы система могла автоматически собираться на их основе. Это потребует тщательного аудита качества, включая ревью изменений, совместную работу, ведение версий с возможностью отката и автоматическую сборку — всё это элементы подхода Docs as Code.
Второй вид документации — описание текущего состояния системы. Чтобы избежать разрыва между описанием системы и её реальным состоянием, предлагается генерировать человеко-читаемое описание на основе кода и конфигурации. Этот подход можно назвать Code as Docs.
Третий вид — пользовательская документация. Её объём будет сведён к минимуму за счёт создания понятных интерфейсов и интеграции подсказок непосредственно в процесс взаимодействия пользователя с системой. Этот подход можно обозначить как No Docs.