Комментарии 39
Agile и полноценная документация вещи противоречащие друг другу.
Поэтому:
- документацию можно и нужно автоматизировать, писать системную документацию к постоянно меняющейся системе руками грех,
- из опыта - удобнее всего когда требования выдаются устно, а аналитик пишет пользовательскую документацию где-то у себя в сторонке,
- API каждого модуля должно быть описано полностью, без этого не будет работать SemVer
"...из опыта - удобнее всего когда требования выдаются устно, а аналитик пишет пользовательскую документацию где-то у себя в сторонке..." - удобно, наверное, да, тк можно распараллелить разработку и аналитику.
Но есть нюанс, как говорится.... "Устную постановку задач" часто встречал, но также часто потом это стреляло в ногу, что у разных людей в голове вырисовывалась разная итоговая реализация и аналитика (которая писалась "в сторонке"). Как итог - аналитика выкидывалась в мусорку, тк переделывать код долго==дорого -> что приводит к bus-фактору и остальным пунктам из данной статьи....
Касаемо agile - все хорошо работает, если процесс выстроен, что не всегда получается... здесь, вероятнее всего, проблема именно планирования.
Если грамотно спланировать, то по agile документация отлично работает. Аналитик должен минимум на 1-2 спринта идти впереди команды разработки - сначала делается документация, в последующих спринтах по полноценной документации - пишется код - строго по документации. Если в ходе написания кода разработчик находит неточности (если аналитик ошибся или поленился воспроизвести весь сценарий "вручную" до автоматизации), то уведомляет об этом аналитика и документация актуализируется - таким образом получается и agile работает и документация в проекте актуальная со всеми вытекающими :)
Мне кажется, вы никогда не работали по Agile. То что вы описываете приводит к Waterfall и одному стори-пойнту равному 40 часам.
Для решения всех указанных вами нюансов есть выработанные практики - три амиго, груминг и планирование. Я захожу иногда на эти ваши стендапы и ужасаюсь статусам "я хожу на встречи и пишу аналитику, сегодня тоже буду ходить на встречи и писать аналитику".
Другое дело когда сессия трёх амиго разрастается до встреч из 30 людей которые слушают перепалку двух людей которые ничего не шарят.
По поводу agile - вы правильно ответили, что вам кажется:) все выше описанное было в рамках продуктовых команд, работающих по agile.
Но глобально я с вами согласен, если команда в целом - довольно зрелая и каждый член команды - ответственный, то таких проблем быть не должно.
Но реальность, зачастую, другая
ну и это... насчет онбординга.
когда в confluence документация копится 10 лет, 99.9999999% её уже устарела, а поиском по ключевым словам находится 4000 документов разных дирекций на одну и ту же тему - это никак не ускоряет онбординг.
периметр не ограничивается одной фичей как правило, и разработчику приходится всегда идти к техлиду, который уже изучил всю систему целиком от фронтов до шины интеграций и знает все реальные подводные камни.
Тех долг тоже необходимо фиксировать не на словах, а "на бумаге", если фиксации не было - значит и тех долг закрыт не будет (забудут/забьют)
Техдолг это когда должны были сделать и не сделали. А задачу закрыли. А в доке написали "А мы так и хотели чтобы кнопка Назад не работала". Дока актуальная? Актуальная. "Видишь техдолг? Нет. А он есть." И он не решаемый потому что в принципе не было анализа реализуемости.
Описанный вами кейс - описание незрелой команды.
Если команда зрелая и ответственная и вдруг по какой-либо причине они решили, что кнопка не будет работать какое то время и выкатились в прод - необходимо фиксировать тех. долг., а не писать в доке "мы так хотели"
Но вообще - выкатываться в прод заведомо зная про багу - плохая практика
Давайте чуть более предметно вести диалог. По CMMI зрелость определяется так:
Зрелая команда - это та, которая делает задачи в срок и знает про баги как known issues. Её работа измерима и предсказуема.
Незрелая - это та, которая не успевает в срок по причине непроработанной аналитики.
Вот вы говорите - делайте актуальную документацию. А как?
Как только есть внешний заказчик, так без документации и фиксации требований никуда.
Каждое решение в кодовой базе должно быть подтверждено:
текстом в запросе клиента (электронная почта годится, все устные требования — фиксируются текстом и получается подтверждение по почте, что всё верно);
созданным на основе запроса клиента артефактом в документации;
прикреплёнными к документации задачами;
логом изменения документации и задач на основании изменения требований клиента.
Как только этим пренебрегают, начинается игра в русскую рулетку на основании доверия заказчику.
В достаточно крупных компаниях и соседний отдел может выступать в качестве внешнего заказчика.
В большинстве случаев такая работа аналитика только упрощает жизнь разработчикам в каскадной модели разработки и нормально определяет зоны ответственности за работу решения (пока бизнес-требования не переведены в спецификации; не согласованы с заказчиком; и не созданы задачи; работа в дело не берётся; а когда берётся, то косяк в спецификации — это ответственность аналитика, а не разработчика).
Зато в случае перехода к досудебным разбирательствам или судебным прениям наличие оснований у каждого принятого решения очень сильно поможет юристам компании отстоять свою правоту.
Согласен, разработка для внешнего заказчика без документации - опасна
достаточно описанных в контракте функциональных и нефункциональных требований.
Автор пришел к целеполаганию:
Документация нужна читателю а не писателю.
Ее объем, вид и язык также зависит от читателя.
Глобально , да - читают документацию чаще, чем пишут (также как и код). Поэтому документация больше для читателя, чем для писателя
Здесь тоже согласен, документаций может быть насколько видов. Например, пользователю системы не нужно знать какие запросы отправляются при нажатии на зелёную кнопочку, но важно чтобы при нажатии на эту кнопочку происходило событие (например, публикация комментария). При этом разработчику важно знать какой запрос должен отправляться при нажатии на ту же самую зелёную кнопочку.
Так вроде и так понятно, что с документацией лучше чем без нее. Тут же вопрос в том, сколько это будет стоить и какой эффект принесет. И все упорно не хотят складывать и умножать суммы денег и человеко-часов и сравнивать их, ограничиваясь фразами - "ну маленьким документация не нужна, а большим нужна".
Наверное, было бы неплохо определить размер проекта между "маленьким" и "большим" когда документация нужна.
И определить затраты на восставновление документации, когда ее не вели пока росли до среднего размера проекта. Возможно, дешевле организовать ведение документации с самого начала.
Плюс, возможно, есть отрасли проектов где не вести документацию просто нельзя. А есть типы проектов, где документацию вести не нужно или ее сделает сообщество вокруг вашего продукта.
И главное, до всего этого было бы неплохо определить оптимальный/минимальный состав ""документации"", от которой была максимальная польза для облегчения онбординга, тестирования и прочих кейсов использования.
Вот это был бы анализ.
к сожалению, не всем понятно, что с документацией лучше, чем без нее. Как пример, в моей прошлой статье (https://habr.com/ru/companies/alfa/articles/853396/) почитать комментарии, где несколько человек утверждало, что документация не нужна - это породило у меня идею свести аргументы в отдельную статью....
Что касается вашего предложения по анализу зависимости документации от проектов - интересная идея для будущих статей, спасибо)
Это не вопрос из разряда бинарных: можно обойтись без документации или нет? В такой постановке сразу читается две крайности, где "справа" - тонны текста и картинок. А дело в необходимом и достаточном наборе артефактов и степени детализации их содержания! Ведь на каком-то проекте хватит user stories + BDD, а на другом нужно готовить ТЗ, ЧТЗ, ТП и далее C4 схемы, набор use cases с sequence diagram, ER диаграммы и т.п.
Если в компанию приходит глухонемой разработчик, умеющий читать и писать, и он способен сразу начать писать код и приносить пользу, то в такой компании с документацией все в порядке. Если нет, то с документацией беда. Мало компаний способны пройти "тест глухонемым разработчиком" и вот почему: Документация обнуляет много крикливых паразитов на проекте, чья значимость сильно раздута. Эти паразиты не могут этого позволить и поэтому всячески препятсвуют созданию качественной документации.
Отсутствие документации создает доп нагрузку и требования. Дошло до того, что стали требовать софт скилы от технарей!!! Более уродливого сценария сложно было представить!
Про доп нагрузку - полностью поддерживаю. При этом иногда люди, о которых вы писали в предыдущем комментарии или действительно не замечают этого, либо делают вид, что не замечают этого
Про необходимость софт скиллов не могу полностью согласиться, т.к , на мой взгляд, софты важны вне зависимости от наличия/отсутствия документации)
Документация, ревизия кода, рефакторинг, работа с техдолгом, чеклисты, тесты, митинги, риск-менеджмент, бюрократия - это не то, за что заказчик платит с удовольствием.
я 10 лет безуспешно в альфе пытаюсь заставить команды все документировать
и дело в том что ребята в моменте не ощущают проблем
серьезные проблемы действительно редки
например
а) команда уходила в полном составе со всей экспертизой
б) переезд на другие сервера (чтобы знать какие сетевые заявки завести, нужно знать какие ВНУТРЕННИЕ И ВНЕШНИЕ интеграции есть и IP адреса куда и откуда стучаться к новым серверам)
в) срочный боевой дефект в бизнес-процессе который давно работает и на нем нет постоянной команды (т е дежурная команда должна быстро разобраться в чем дело)
г) служба безопасности запрашивает алгоритмы пайплайнов для проверки на уязвимости
д) служба безопасти запрашивает описание как хранятся данные или логи для составления списка систем с чувствительными данными и проработке мероприятий по их защите
когда наблюдаешь это вживую - это очень похоже на ЖКХ которые внезапно увидел снег
а еще отсутствие документации один из аргументов, когда директора обсуждают должна ли система существовать или лучше создать новую
но это мелочь - программистам ведь не привыкать выкидывать код, на который потратили свое время =)
"... Серьёзные проблемы действительно редки... " - но зато их цена может быть очень высокой:)
Пример с ЖКХ - огонь:)
Нужна ли документация на проекте?