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