Comments 24
Сам следую давно похожему подходу.
Но есть одно но. Такая мелкогранулированная и сильно привязанная к конкретному модулю документация должна храниться вместе с исходным кодом в виде, например, файла README.md
В конфлюенсах лучше держать что-то более общее
Cпасибо за комментарий. Мы тоже об этом думаем, но пока не пришли к подходу хранения доки рядом с кодом.
Что-то более общее, это вы про что? Сможете привести пример? и что из этих разделов кажется слишком мелких для condluence?
Мы храним документацию в коде при помощи asciidoc +pluntUML. Достаточно удобная структура, но есть нюансы в том, что когда документ попадает в код, то все что было в конфе становится неактуальным и приходится архивировать.
Советую обратить внимание на https://backstage.io/. Можете получить удобство confluence/notion. При этом хранить документацию и рядом с кодом, и отдельно
А не логичнее будет заносить эту информацию в код и уже из кода генерировать документацию для конфлюенса, свагера и др? Это же гораздо проще чем синхронизировать код с конфлюенсом.
По нашим процессам - это ТЗ для разработчика, он смотрит на доку и пишет код. А вы предлагаете заносить эту инфу в код.. Кто, как вы думаете, это должен делать? Поделитесь, плиз, видением..
Насчет должности не знаю, но так то это и системный аналитик может делать. Освоить базу языка это просто. Этот человек должен описать в коде контракт и документацию к нему, но не реализовывать логику. Далее из этого контракта сгенерируется документация в необходимые места, а разработчик напишет логику. Тем самым вы сильно сократите объем работы и жизнь разработчику. И это еще не трогая таких моментов что СА не ванга, и не может со 100% точностью описать контракт заранее, что бы его не пришлось править разработчику.
Спасибо за пояснение. Да, это было бы удобно в случае, если аналитик может базово кодить или разработчик сам проектирует API. Время до выпуска апи на тест сократилось бы.
Любопытный подход. Если с генерацией сваггера из кода в целом понятно (есть много библиотек, например, для спринга: springdoc-openapi и тд), то вот вот остальная документация (описания алгоритма, какие-нибудь общие требования и контекст, напрямую не связанные с механикой общения между сервисами) не понимаю, как можно генерить по коду. Есть какие-то библиотеки интересные на эту тему, как со сваггером у спринга?
Не совсем понял. Какая последовательность действий СА?
Сначала текстовое описание методов, затем контракт OpenAPI или наоборот?
Если наоборот, откуда СА будет брать инфо в процессе описания контракта - держать в голове?
Нарушен прицип "specs firs". С OpenAPI (бывший swagger) так работать непродуктивно. Лучше наоборот - написать спеку в формате OpenAPI (ее как раз уже хорошие системные аналитики вполне могут сделать), а разработчик уже нагенерирует из нее и модели, и заготовки для серверов и много что еще может, в том числе и отдельную документацию. И при этом код уже будет аннотирован и размечен как нужно информацией из вашей спеки. Вот онлайн редактор https://editor.swagger.io/, в нем уже по дефолту некоторый пример залит, как нужно размечать. Можно работать прямо онлайн. Справочные материалы в меню About )
А если в процессе разработки многое меняется, то нужно постоянно актуализировать описание? Т.е. работаю в паре разработчик и аналитик всякий раз?
Хорошая статья, очень пригодится для начинающих аналитиков и тем, кто только вливается в проект с нуля и надо как то стандартизировать документацию
С перечисленными пунктами в ТЗ интересно, полезно. Но с их реализацией есть вопросы. Как уже сказали описать контракты и схемы БД в ручную требуется время, при этом в момент разработки они чаще всего меняются. Поэтому эти пункты должны лежать ближе к коду, это позволит разработчику поправить их, при реализации. Мы генерируем схему БД и OpenAPI из кода.
Интересно по пункту со поведенческой схемой, у вас достаточно это программистам? А схема компонентов? А сценарии(UseCase) в виде блок-схем?
Спасибо за ваш комментарий. Что вы имеете ввиду под сценариями в виде блок-схем? Если вы про usecases, то они у нас прописаны в документации на фронт. Писала про это в статье: https://habr.com/ru/company/ru_mts/blog/686570/
А для микросервисов достаточно того, что описано в статье. По крайней мере доп.запросов не было еще.
Заголовок "Как создать шаблон", а содержание - чем заполнить шаблон. Или тема не раскрыта, или заголовок не подходит к тексту.
Покритикую немного
Описание API в текстовом виде в конфлюенсе - зло. Такое описание может вполне сойти за ТЗ разработчику, который погружен в проект и у которого аналитик всегда под рукой, но для внешних пользователей бесполезно. Для внешних пользователей это должна быть спецификация openapi и примеры рабочих (с корректной авторизацией и корректными dto) запросов, которые можно выполнить самостоятельно.
Описание БД в текстовом виде в конфлюенсе тоже считаю избыточным. Разрабу оно не нужно и оно устареет после первого спринта. Если на помощь все равно нужны или архитектор или разработчик, то легче выгрузить модель из реальной БД.
Но в целом статья понравилась своим целостным подходом.
Приятно случайно наткнутся на статью и понять, что у себя я организовал примерно тоже, что и у других. Видимо тут в целом ничего сильно лучше не придумаешь. Спасибо за статью.
Можно дополнить шаблон разделами про асинхронное взаимодействие (перечень каналов через Kafka/Rabbit) и со сценариями использования сервиса; а в разделе про REST отдельно упомянуть про список ошибок и аутентификацию.
Как создать шаблон документации к микросервису