Комментарии 38
А можно поинтересоваться - зачем вам вся эта макулатура? Что есть конечная цель? Ну вот допустим у вас на руках большой проект. В нем 100500 sequence diagrams, описана схема данных (а так ее что не видно через FK в SQL базах или по связям в ORM?) и все такое. Что теперь вы будете с этим делать и что будут делать другие? Давайте оставим за скобками проблемы аудита. Нужна документация программистам? Они будут ее читать? Не джуны, а все остальные. Если не будут, то скорее всего она вам и не нужна. Я ничего не скажу про аналитиков - им надо - вот и пусть пишут и поддерживают. Мне кажется, что единственная документация - это код и все что из него можно сгенерировать. Все остальное или не нужно или устарело.
код - это отличная документация в рамках системы, если у вас монолит, а если система распределенная (система состоит из множества модулей-микросервисов)?
например, у вас 100 микросервисов - прилетает баг с прода...
как без документации локализовать проблему?
как понять, что пофиксить нужно "вон тот" микросервисе, мы ошиблись и необходимо доработать логику "вот так"
В рамках микросервисов есть OpenAPI - там и код и документация в одном. Я к тому, что даже если вы доку написали один раз ее потом всю жизнь надо поддерживать. У вас есть на это бюджет, желание и ресурсы? Если нет, то выход один - код лучшая документация (@ValeryGL). Просто не надо разделять их. Отдельная документация устаревает в момент сохранения файла (а то и раньше). В итоге дока как-бы есть, но ее как бы и нет. По этому только доко-генерация (которую можно и не делать) и редкие статейки на вики, которое никто не читает :)
Согласен с тем, что разделять код и Доку не нужно, но одного кода не достаточно. Подтверждение в моём примере выше с багом и сотней микросервисов.
Основной ваш посыл в том, что документацию дорого содержать в актуальном состоянии - ещё дороже не иметь документацию. Посчитайте насколько дешевле онбординг новых сотрудников при отсутствии документации , посчитайте насколько дороже анализ и фикс багов.
Возможно, вы правы, что описание излишне, когда весь проект - это пара сервисов, но в крупном проекте без актуальной документации крайне сложно. О том, что необходимо прививать культуру документирования - это также отмечено в статье
Документация из кода это капля в море и заявлять, что ее достаточно - крайне опрометчиво.
Во-первых, у вас описаны сценарии и бизнес процессы, которые формируются на стадии проекта.
Во-вторых, на старте часто просят сайзинги, что бы закупать железо, а вашего кода еще нет и в помине.
Можно продолжать бесконечно, тесты, си/сд, отчеты безопасности и многое другое, что хотят знать сейчас потребители - это все документация
"Мне кажется"
- главное, чтобы это кому-то было действительно реально нужно - очевидно что это и те..., кто придёт читать тот код, который был написан ушедшим разработчиком... и да, важно, чтобы сама документация была предельно простой и понятным образом организована..., чтоб те, кто будут ею пользоваться не теряли время на доп. обучение...
Начав читать ваш комментарий, уже придумал на него смешной аргумент "вы еще скажите, что код - лучшая документация".... упс, так уже шутили?
У разработчика два состояния:
через месяц после релиза, если сам сумел разобраться в своем или соседском коде - "там все понятно, и вообще код - лучшая документация". Ну и сразу после своего релиза то же самое.
А если не разобрался - "там ничего непонятно, пусть аналитик нам все расскажет"
Если вы работаете в компании-интеграторе, то у вас нет доступа к проду и к данным с прода (если он есть, то нужно сделать все, чтобы от него избавиться, так как последствия утечки или изменения чего-либо на проде у заказчика могут быть катастрофическими).
Есть "бледная копия настоящей системы" на средах DEV и TEST в виде того компонента, с которым работает ваша фирма по договору и, если повезет, парочки соседних компонентов, наиболее значимых, но не всех. При этом компоненты "мертвые": там нет пользователей, реальных записей тоже (только оставшиеся с прежних времен какие-нибудь тестовые), отсутствуют логи и т.д. Понять, как работает система при таких вводных - нетривиальная задача.
Программисту документация действительно не нужна, ему нужна задача. А поставить вы ее как системный аналитик не можете так как просто не от чего оттолкнуться.
единственная документация - это код и все что из него можно сгенерировать
Это работает ровно до тех пор, пока ты пишешь код, который не используется нигде повторно. Как только ты пишешь что-то, что должно использоваться многократно, тебе нужна документация. Причём в первую очередь у документации должна быть очевидная точка входа, где будет расписано, что к чему.
Например, есть фронтенд-приложение, которое общается с бэкендом, используя авторизацию через JWT-токены. В таком случае имеет смысл написать свой http-агент, в который будет зашит домен бэкенда плюс логика валидации и обновления токенов также должна быть зашита в агент. Пока ты этим пользуешься, всё хорошо, но потом приходит второй разраб, и когда ему надо будет сделать запрос на бэк, он напишет запрос через fetch, а токены валидирует и добавит в запрос вручную. Потом через неделю выяснится, что обновление токена у него вообще не было реализовано, и он потратит на это ещё день вместо того, чтобы сразу взять готовый агент. И вот тут как раз становится понятна роль документации: там должно было быть ясно сказано, что для http-запросов нужно использовать агент, который лежит вот там. То есть докуменация не должна объяснять работу кода, а должна регламентировать использование типовых решений для тех или иных задач.
Ну или компонентный дизайн - он вообще не будет работать без документации. Пока нет списка компонентов, каждый фронтендер будет делать свой компонент для одних и тех же задач.
Проект сотни тысяч строк, разобраться что в нем происходит - много месяцев.
Для подобного проекта, документация несколько сотен страниц - за несколько недель можно вникнуть.
Очень хочется иметь схему взаимодействия модулей / пакетов / блоков кода. То есть бизнес процессы уже с кодом. Видеть и процессы и код почти одновременно. Тут мы сдвигаемся в крупноформатное визуальное программирование и будут возражения - от кому это надо, как это поддерживать в актуальном состоянии, до - а как это отлаживать? И ещё это полностью не помещается на экране, убогость ограниченности отображения в стандартных символах/ фигурах, дубляж информации в коде и в диаграммах, проблемы синхронизации кода и диаграмм.
Возражений много, только это сильно облегчает работу всей команды. И даже если вы один на проекте, то вспоминается многократно быстрее, сохраняет множество часов и нервов. Хотя конечно, что бы задокументировать, нужно тоже потратить время и иногда возникают ощущения, что все эти труды впустую и это никому никогда не пригодиться.
В 2024 появился чит, который работает - собрать имена всех файлов, пути, классы, сигнатуры методов (без имплементации), структуру баз данных ну и целиком код из роутинга ендпоинтов. Собирается шелл скриптом / батником автоматически в один текстовый файл, потом этот текстовый файл загружаем в клод соннет 3.5 либо оупенаи о1 - и оно все досконально рассказывает о чем этот проект. Ну и дальше когда понятна о чем проект в целом собирать таким образом уже отдельные модули / неймспейсы уже с реализацией и опять спрашивать у ллмки загрузив контекст. Ещё весной-летом это всё было лажей и не работало, последние пару месяцев реально работает. Но, важно, чтоб кодовая база более ли менее следовала базовым кодинг стандартам по неймингу и имела более ли менее вменяемую архитектуру.
Если LLM развернут на внутренних серверах, то наверное можно провернуть такое (я не пробовал), но если использовать условный chatGPT, который на стороннем сервере - то могут возникнуть вопросики от службы безопасности...
Если я правильно понял, то сами интеграции между сервисами (кто кого и в какой последовательности вызывает) - все равно придётся описывать вручную?
Но в целом идея минимизации трудозатрат интересная)
В моем случае я просто попросил Клода написать мне батник который пробежится по проекту и соберет все сигнатуры под конкретный ЯП проэкта, запускал этот батник и скармливал ллм мол "о чем тут все, опиши архитектуру". При чем информации в какой последовательности и как у него в принципе не было, я это не описывал вручную, это он все домысливал сам, но совершенно правильно! Если там какие-то неочевидные интеграции или сложные последовательности на фронте, то ему видимо придется скормить ещё кусочки фронта, но в моем случае хватило просто апишки (немаленькая под сотню ендпойнтов) - целиком роутинг, целиком некоторые особо хитрые контроллеры, все остальное чисто сигнатуры . Ну и на текущий момент сэлф-хостед ллм решения типа ЛЛамы скорее всего подобное не потянут и много где нагаллюцинируют. Это большое преимущество новых моделей от топ провайдеров интеллектов - им даже особо описывать вручную ничего не надо, они до всего сами докумекают по контексту.
интересное решение)
знаю, что сейчас делают аналогичное решение на внутренних мощностях в одном из банков))
в части документирования диаграмм последовательности (а это важный аспект документации) - не пробовали тоже как-то автоматизировать процесс?
или у вас монолит и в целом документация одного большого сервиса/модуля покрывает условные 99% запросов клиентов?
Ну да, в кровавом энтерпрайзе подобное решение типа "а давайте отправим структуру нашего кода в облака заклятым друзьям", пожалуй загнется ещё на уровне согласования с СБ. :) Да и в целом ограничения по контекстному окну начнут играть большую роль. Но учитывая скорость с которой опен-сорс ллм догоняет китов, в очень ближайшем будущем подобная авто-документация должна стать стандартом. Ну и конечно всякие банки, мобильные операторы и яндексы здесь будут первыми.
Конкретно это решение - достаточно крупный монолит, так что одной общей документации хватает. Достаточно путанный монолит с сильным коуплингом, но с хорошим следованием нейминг-конвенциям, а это для ЛЛМ пожалуй самое важное.
В bpmn-нотацию УЖЕ может но ПОКА ЧТО так себе, тут придется в режиме дискуссии уже с ллмкой работать. Т.е. xml для импорта в какой-нибудь draw.io он создаст, дорожки, действий и шлюзы понатыкает, но пока что это всё достаточно криво и доделывать придется. Ну в моем случае это было и не надо, это я уже так для интереса посмотрел сейчас.
Аналитики, похоже, скоро будут не нужны.
Спасибо, очень интересная статья. Как раз пишу документацию с нуля на новом месте. Думаю, воспользуюсь частично вашими гайдами)
Очень жизненная и полезная статья. Тоже делала такое, но на монолите и без баз данных.
Спасибо, все очень хорошо описали. Занимался подобным несколько раз, но несколько в другой последовательности и с монолитом:
1. Описание UI.
2. Описание модели данных.
3. Описание решаемых задач.
4. Подготовка задач на развитие.
На первый взгляд, как же так, ведь самое важное - это какую ценность решение имеет для бизнеса? - надо начинать с п.3! - В реальности самостоятельная работа с UI позволяла уже в первом приближении разобраться, с чем работают пользователи, и это позволяло подготовить вопросы для встреч с ними с выяснением вопросов как и зачем они с этим работают. Пункт 2 шел параллельно, с командой разработки.
Последовательность шагов поэтому, наверное, не должна быть жесткой.
Спасибо, что поделились вашими опытом)
Да, согласен, последовательность шагов может варьироваться
А можно уточнить, вы статью писали с точки зрения разработчика, аналитика или аналитика-разработчика?
В статье я уточняю, что повествование от лица совмещённой роли системного и бизнес аналитика)
Но в роли разработчика я также бывал на проекте, где не было документации... В целом там приходилось проходить +- аналогичный путь (единственное, что там большинство пунктов сводилось к чтению кода, но не все пункты), чтобы понять как все работает...
В конце статьи правильно подмечено, что состояние документации (да в принципе её наличие) зависит от уровня зрелости команды. Вообще вся эта затея с восстановлением документации действительно имеет смысл только в том случае, если инициатива не только была поддержана и одобрена проектным руководством, но и был выстроен процесс постоянного поддержания документации в актуальном состоянии, с которым согласились все заинтересованные лица. Иначе аналитики окажутся в ситуации худшем, чем Алиса из Страны чудес.
Что делать, когда попал на проект без документации