Какие главные проблемы технической документации? Во-первых, ее нет, во-вторых, если она есть, то не актуальна.
Давайте порассуждаем, как мы можем попытаться упростить себе жизнь при создании документации, а главное увеличить ее актуальность и качество.
Существует три класса задач, которые решает техническая документация:
Описать наши требования к системе и принятые решения
Описать текущее состояние системы
Объяснить пользователю, как работать (\разворачивать\эксплуатировать) с системой.
Первый тип документации - наши требования к системе. В эпоху LLM, кодогенерации и декларативного подхода к описанию инфраструктуры, мы будем вести требования так, чтобы система, там где это возможно, сама собиралась из них. Поэтому документация первого типа потребует высокого аудита качества. Ревью изменений, совместная работа, ведение версий, с возможностью отката, автоматическая сборка. Все то, что присуще подходу Docs as Code.
Второй тип документации - описание текущего состояния системы. Так как мы не хотим разрыва между описанием системы и самой системой, мы будем пытаться генерировать человеко-читаемое описание из кода и конфигурации. Назовем этот подход Code as Docs.
Третий тип - различные виды пользовательской документации. Эту форму документации мы постараемся минимизировать, сделав понятным наши интерфейсы и встроив подсказки прямо в процесс работы пользователя с системой. Назовем это подходом No Docs.
На этом можно было бы и закончить, но пройдемся подробнее по каждому пункту.
Docs as Code
Вы никогда не думали, что делая подробное ТЗ вы делаете двойную работу? Вначале аналитик подробно описывает все алгоритмы и спецификаци��, а потом разработчик делает то же самое, но на другом языке. Конечно, этот тезис имеет множество оговорок. Код обычно содержит больше деталей, таких как: исключения, логирование, деление выполнения на синхронную и асинхронную составляющую и другие нюансы реализации. Но в современном мире есть множество способов уточнять эти детали за пользователя, от стандартизации подходов и вынесения их в платформу или библиотеку, до генерации через агентных систем на основе LLM.
Конечно всегда остается исключительно текстовая документация: ADR, исходные бизнес требования и пр. Но раз мы все ведем как код, почему бы нам не делать так же и с ними?
Если мы имеем достаточное описание системы на естественном языке (или в нотациях понятным человеку, например OpenAPI или Proto), то мы должны стараться минимизировать дублирование тех же требований в коде. Тогда мы будем стараться использовать наши описания для кодогенерации везде, где это возможно. Такой подход определяет два вывода:
Формат документации должен быть удобен для кодогенерации.
Жесткий контроль качества документации. А именно: ревью, хранение версий, линтеры и т.д. Все что свойственно подходу Docs as Code.
Очевидной альтернативой является фиксация требований сразу в виде кода. С учетом развития агентских систем, это примерно тоже самое, вопрос лишь в каком месте процесса стоит агент. Сравните:
Фиксация документации, генерация кода из документации. Человек пишет требования на естественном языке и фиксирует документацию, контролирует ее корректность и обеспечивает качество. При запуске сборки CI\CD платформа генерирует код алгоритмами, там где это возможно, или отправляет агенту задачи генерации.
Генерация кода из документации, фиксация кода. Человек с помощью агента преобразует требования из описания на естественном языке в код. Человек фиксирует код, контролирует его корректность и качество. При этом он обращается к LLM для преобразования описания с естественного языка в код.
Сейчас все работают именно по схеме фиксации кода. Это достаточно понятно, пока нет 100% доверия агентским системам. Но первый вариант дает доступ к концепции NoCode, которая уже давно будоражит умы всех крупных корпораций и стартапов.
Может показаться, что при переходе к первой картинке из процесса исключается разработчик, так как его заменяет CI/CD-платформа, работающая с документацией . Но скорее произойдет расширение зоны ответственности разработчика и аналитика. И вероятно в этой роли гораздо комфортнее будет разработчику, так как без человека который сможет прочитать сгенерированный код и подтвердить, что он достаточного качества, процесс пока не запустится. Но тренд на рост числа системных аналитиков для формирования подробного ТЗ на понятном разработчику языке видится бессмысленным. При этом роль бизнес (или продуктового) аналитика в таком подходе никуда не исчезает. Нам все еще нужно, чтобы кто-то взаимодействовал с пользователями, выяснял что им нужно и фиксировал базовые требования.
Доминирующий инструментарий — это связка легковесных языков разметки (markdown или asciidoc), диаграмм в формате кода (plantUML, mermaid, Structurizr и пр), GitLab или GitHub в качестве хранения и визуализации и встроенные в них инструменты для запуска генерации и преобразования исходных документов. Иногда добавляют генерацию статических сайтов на основе документов, но с текущими возможностями рендеринга md и adoc документов в GitLab или GitHub их вполне можно использовать для конечного просмотра. Добавьте ко всему этому вашу любимую IDE с необходимыми плагинами и получите готовый инструментарий для внедрения.
Code as Docs
Мы подходим ко второму типу документации - описание того, что есть сейчас, напрямую из кода или состояния системы. Отрасль шагнула сильно вперед в этом направлении. Есть подходы Infrastructure as Code, Architecture as Code, Everything As Code (с разной степенью проработки). Есть множество декларативных языков и средств визуализации понятных человеку, даже если он не является специалистом. Кроме того множество инструментов могут генерировать документацию из кода (Java doc, Go doc, Open Api и пр) Такие инструменты уже сейчас снижают разрыв между реализацией и документацией.
Подходы самодокументирования корректно было бы назвать Docs from Code, но мы хотим пойти дальше. Только код в полной мере описывает работу системы. Даже подробное ТЗ со всеми нюансами не может гарантировать, что система ему соответствует. Во-первых, система могла развиваться и уйти дальше от своего описания, которое просто пока не обновили, во-вторых, реализация может просто содержать ошибки. Кодогенерация может снизить объем проблем, но все равно остаются точки отказа. Могут быть ошибки в инструменте генерации или, просто, не весь код является сгенерированным.
Агентские системы могут расширять возможности генерации описания и визуализации на основе кода и конфигурации системы. Не сложно спроектировать систему, которая будет генерировать описание модулей система, на основе кода. В первом приближении это может быть RAG приложение подключенное к проиндексированному репозиторию с кодом. Пользователь может выбирать модули из меню или писать напрямую агенту “Как работает модуль?/Какие случаи использования не покрывает текущая реализация?/На каких серверах развернуто приложение?/Какие лимиты выделены для сервиса, достаточно ли их для нормальной работы?”. Агент на основе разметки находит нужные части кодовой базы или конфигурации (которые конечно хранятся в том же репозитории, так как мы давно перешли на Infrastructure as Code). В таком случае мы будем использовать код как источник истины, чем он по сути и является.
В итоге пользователь наблюдает всегда актуальное описание логики работы системы и ее состояния.
Имеющиеся инструменты для генерации документов на основе кода отчасти мы уже перечислили выше. Указанный инструментарий далеко не избыточный. Я думаю вы без труда найдете средства для генерации документов и визуальных представлений для используемых вами технологий. Но для чтения кода без знаний языка готовых инструментов пока нет. Сейчас нам доступны только ручной поиск нужных частей кода в репозитории с прямым запросом в LLM или разработка собственных решений.
No Docs
Документация для пользователя в ее классическом виде уступает место другому подходу — бесшовному взаимодействию, которое развивается под названием UX/UI. Наше взаимодействие с пользователем должно быть понятным и привычным для него. Если мы пониманием, что действия пользователя по достижению результата непонятны ему, гораздо правильнее встроить подсказки (а возможно и отрывки документации) прямо в интерфейс. Таким образом для пользовательской документации мы выберем подход без документации или No Docs.
Стоит оговориться, что нашими пользователями на самом деле являются не только те, кто используют систему, но и те, кто ее разворачивает и обслуживает. Эти люди также требуют заботы и продумывания их опыта взаимодействия с системой. Конечно, этот класс пользователей зачастую может сам о себе позаботиться, но надо хотя бы им не мешать делать это.
Всегда остаются случаи, когда наличие руководства пользователя\администратора - требование, без которого систему невозможно ввести в эксплуатацию, или система настолько непривычна пользователю, что без разъяснений не обойтись. Но наша цель дать пользователю простой и понятный интерфейс, который говорит сам за себя.
Инструменты создания понятных интерфейсов известны - это тысячи часов проектирования и оттачивания на основе обратной связи от пользователей. Экономия на документации точно не стоит потраченного времени. Но только так можно сделать продукт конкурентным на рынке и любимым для пользователями.
Итого
Мы описали идеализированную картину, когда документация содержащая требования к системе создается по принципу Docs as Code и активно используется для генерации кода. Текущее состояние системы собирается в удобный для чтения человеком вид из кода и конфигурации системы по принципу Code as Docs, и наша система спроектирована таким образом, что забота о наших пользователях — как конечных пользователях приложения, так и администраторах, которые его разворачивают и поддерживают заставляет нас делать их опыт работы с нашим приложением максимально простым и удобным, так что им просто не нужна пользовательская документация, мы назвали это принципом No Docs.
Трудно спорить, что концепция техно-оптимистична, сейчас нет коробочных инструментов, которые связали бы все тезисы воедино. Но это не помешает нам внедрять элементы этих подходов в тех местах, где этот даст максимальный эффект. Нет необходимости сделать все и сразу. Вспомните те проблемы, которые у вас были в последнее время из-за отсутствия или неточности документации. И начните их решать приведенным подходом или любым другим.
