"...из опыта - удобнее всего когда требования выдаются устно, а аналитик пишет пользовательскую документацию где-то у себя в сторонке..." - удобно, наверное, да, тк можно распараллелить разработку и аналитику.
Но есть нюанс, как говорится.... "Устную постановку задач" часто встречал, но также часто потом это стреляло в ногу, что у разных людей в голове вырисовывалась разная итоговая реализация и аналитика (которая писалась "в сторонке"). Как итог - аналитика выкидывалась в мусорку, тк переделывать код долго==дорого -> что приводит к bus-фактору и остальным пунктам из данной статьи....
Касаемо agile - все хорошо работает, если процесс выстроен, что не всегда получается... здесь, вероятнее всего, проблема именно планирования. Если грамотно спланировать, то по agile документация отлично работает. Аналитик должен минимум на 1-2 спринта идти впереди команды разработки - сначала делается документация, в последующих спринтах по полноценной документации - пишется код - строго по документации. Если в ходе написания кода разработчик находит неточности (если аналитик ошибся или поленился воспроизвести весь сценарий "вручную" до автоматизации), то уведомляет об этом аналитика и документация актуализируется - таким образом получается и agile работает и документация в проекте актуальная со всеми вытекающими :)
В статье я уточняю, что повествование от лица совмещённой роли системного и бизнес аналитика)
Но в роли разработчика я также бывал на проекте, где не было документации... В целом там приходилось проходить +- аналогичный путь (единственное, что там большинство пунктов сводилось к чтению кода, но не все пункты), чтобы понять как все работает...
Если речь про документирование через LLM , то здесь сначала написали код, а потом его задокументировали через LLM.
Но зачастую сначала пишут документацию (аналитику) и на ее основании уже пишут код - если придерживаться вашего комментария, то при данном подходе не нужны будут программисты?)
еще зачастую бывает так, что по результатам встречи не фиксируются договоренности (условный протокол). следующая встреча начинается с того, что минут 10 (вроде, мало,но умножьте это время на количество людей в созвоне и на рубли - получится человекочасы неплохие, если это регулярная проблема) вспоминают о чем договорились в прошлый раз, вместо того, чтобы открыть протокол предыдущей встречи и экономии тех самых условных 10 минут...
"""...Exactly once...их считывание не идемпотентно... Например операции с платежными транзакциями.""" Операции с банковскими транзакциями не идемпотентны? Вероятно, не самый удачный пример?
если в ходе написания вашей документации с нуля на текущем проекте - появятся инсайты по возобновлению документации - буду рад, если поделитесь в комментариях)
знаю, что сейчас делают аналогичное решение на внутренних мощностях в одном из банков))
в части документирования диаграмм последовательности (а это важный аспект документации) - не пробовали тоже как-то автоматизировать процесс? или у вас монолит и в целом документация одного большого сервиса/модуля покрывает условные 99% запросов клиентов?
Если LLM развернут на внутренних серверах, то наверное можно провернуть такое (я не пробовал), но если использовать условный chatGPT, который на стороннем сервере - то могут возникнуть вопросики от службы безопасности...
Если я правильно понял, то сами интеграции между сервисами (кто кого и в какой последовательности вызывает) - все равно придётся описывать вручную?
Но в целом идея минимизации трудозатрат интересная)
Согласен, разработка для внешнего заказчика без документации - опасна
"...из опыта - удобнее всего когда требования выдаются устно, а аналитик пишет пользовательскую документацию где-то у себя в сторонке..." - удобно, наверное, да, тк можно распараллелить разработку и аналитику.
Но есть нюанс, как говорится.... "Устную постановку задач" часто встречал, но также часто потом это стреляло в ногу, что у разных людей в голове вырисовывалась разная итоговая реализация и аналитика (которая писалась "в сторонке"). Как итог - аналитика выкидывалась в мусорку, тк переделывать код долго==дорого -> что приводит к bus-фактору и остальным пунктам из данной статьи....
Касаемо agile - все хорошо работает, если процесс выстроен, что не всегда получается... здесь, вероятнее всего, проблема именно планирования.
Если грамотно спланировать, то по agile документация отлично работает. Аналитик должен минимум на 1-2 спринта идти впереди команды разработки - сначала делается документация, в последующих спринтах по полноценной документации - пишется код - строго по документации. Если в ходе написания кода разработчик находит неточности (если аналитик ошибся или поленился воспроизвести весь сценарий "вручную" до автоматизации), то уведомляет об этом аналитика и документация актуализируется - таким образом получается и agile работает и документация в проекте актуальная со всеми вытекающими :)
да, полностью согласен, постепенно приходилось выстраивать процесс выстраивания документирования. команда проходила через все стадии кривой....
В статье я уточняю, что повествование от лица совмещённой роли системного и бизнес аналитика)
Но в роли разработчика я также бывал на проекте, где не было документации... В целом там приходилось проходить +- аналогичный путь (единственное, что там большинство пунктов сводилось к чтению кода, но не все пункты), чтобы понять как все работает...
Спасибо, что поделились вашими опытом)
Да, согласен, последовательность шагов может варьироваться
Если речь про документирование через LLM , то здесь сначала написали код, а потом его задокументировали через LLM.
Но зачастую сначала пишут документацию (аналитику) и на ее основании уже пишут код - если придерживаться вашего комментария, то при данном подходе не нужны будут программисты?)
да, однозначно так и есть)
при наличии документации - каждый новый сотрудник - это валидатор документации
Кстати, интересный пункт про сайзинг, не задумывался о нём ранее, спасибо)
Поделитесь, пожалуйста, были ли какие-либо нюансы при документировании монолита, которые отличаются или дополняют описанные в статье пункты?
еще зачастую бывает так, что по результатам встречи не фиксируются договоренности (условный протокол).
следующая встреча начинается с того, что минут 10 (вроде, мало,но умножьте это время на количество людей в созвоне и на рубли - получится человекочасы неплохие, если это регулярная проблема) вспоминают о чем договорились в прошлый раз, вместо того, чтобы открыть протокол предыдущей встречи и экономии тех самых условных 10 минут...
Спасибо большое за классную статью!
Уточняющий вопрос:
"""...Exactly once...их считывание не идемпотентно... Например операции с платежными транзакциями."""
Операции с банковскими транзакциями не идемпотентны? Вероятно, не самый удачный пример?
успехов в этом непростом деле)
главное не перегореть!
рад, что статья поможет вам)
если в ходе написания вашей документации с нуля на текущем проекте - появятся инсайты по возобновлению документации - буду рад, если поделитесь в комментариях)
интересно, какой опыт был до перехода в it или это первая работа?
эта информация, как мне кажется, может помочь людям оценить свои силы перед марафоном в смене/освоении профессии)
понял, спасибо, что поделились своим опытом)
интересное решение)
знаю, что сейчас делают аналогичное решение на внутренних мощностях в одном из банков))
в части документирования диаграмм последовательности (а это важный аспект документации) - не пробовали тоже как-то автоматизировать процесс?
или у вас монолит и в целом документация одного большого сервиса/модуля покрывает условные 99% запросов клиентов?
Если LLM развернут на внутренних серверах, то наверное можно провернуть такое (я не пробовал), но если использовать условный chatGPT, который на стороннем сервере - то могут возникнуть вопросики от службы безопасности...
Если я правильно понял, то сами интеграции между сервисами (кто кого и в какой последовательности вызывает) - все равно придётся описывать вручную?
Но в целом идея минимизации трудозатрат интересная)
Да, высокое качество документации - это особый навык
Полностью согласен. "Проблемы" документирования тоже есть...
Из ваших аргументов в пользу документирования добавлю ещё, что документация кратко ускоряет онбординг новых коллег
Как по живому прям...)