Comments 9
Не проще ли описывать API через OpenAPI, чем вести такую документацию? А для истории изменений существует git
В статье описан чисто мой субъективный опыт работы с не самыми простыми проектами, где много бизнес-логики внутри API, интеграций с третьими системами и огромное кол-во потребителей документации с уровнем ниже возможности прочитать свободно код и быстро разобраться. OpenAPI - круто помогает в работе, но не закрывает полностью всех потребностей , к сожалению
А как вы считаете, стоит ли уделять больше внимания документации в условиях Agile,
Документация - это одна из множества форм коммуникации. Её разработка и использование могут быть дороже других форм, например, дороже, чем "написать-ответить в чатик". И ещё она в отличие от других форм помогает минимизировать риски (сделать не то, понять не так, забыть, протерять). В то же время, в пересчёте на сроки проекта документация может стать дешевле других форм (в контексте отдельных задач). А может быть так написана, что никакие риски не уменьшает, а увеличивает, и вообще наводит смуту.
Так что "уделать внимание" нужно, если вы понимаете, что это поможет вам сэкономить и/или подстраховаться. И решение принимается для каждого проекта индивидуально, и возможно, для каждой задачи.
несмотря на стремление к гибкости?
Гибкость же не самоцель.
Спасибо, ценный коммент, согласна на 100%. Зависит от проекта, команды, и еще кучи факторов. Я бы проанализировала: есть ли вообще сейчас проблемы в коммуникации? Есть ли неточности/непонимания в требованиях из-за чего увеличивается ТТМ? Какой сейчас процент ресурсов занимают созвоны по задаче/общения в чате в процессе разработки?
А отсюда уже принимать решение, ключ это к успеху или нет.
>Гибкость же не самоцель.
Гибкость - было скорее как "модное" слово, которое часто упоминают. По итогу все мы хотим, чтобы фичи реализовывались быстро, а отсюда и прибыль наша росла. Поэтому скорее имела в виду, что важно находить баланс: где нужна адаптивность, а где чёткие процессы и структуры дадут больше выгоды. Если излишняя гибкость замедляет работу и создаёт хаос, то это уже не преимущество, а ребят, у вас проблемки)
Я считаю, что документация нужна, в меру, но нужна. Это я на своём опыте работы с легаси системой основываюсь, где из документации - три хайлевел схемы интеграции с другими системами десятилетнней давности (где части систем уже не существовало в природе), четыре документа с бизнес-требованиями, которые были разработаны лет 15 назад и утратили окончательно актуальность лет 7, тикиты с требованиями и ченсетами за последние 10 лет (а ещё за 5 были безвозвратно утрачены), ну и собственно - код, конфиги, сервисы, которые служили основной документацией.
Конечно считается, что команда должна уметь читать код. Но если система старая и сложная и побывала в руках большого количества разработчиков - сложнее найти нужные места. Добавляем срочные костыли для какого-нибудь старого фикса, о котором могли забыть впоследствии.. Новому сотруднику вообще тяжело во всем этом разобраться. Делать первичнкю оценку - сложно. На тестирование тоже уходит больше времени, потому что больше шансов что-то упустить.
Советы про OpenAPI правильные. А вообще подход называется API First / Contracts First / Schema First.
Лучше вести описание API сразу с помощью инструментов для разработчиков, чтобы потом не синхронизировать документацию и реальное API
P.S. - посмотрите еще в сторону https://typespec.io/
Как по мне, так "самое ненавистное" в работе аналитика - знать, что твой коллега когда-то не оформил требования/постановку должным образом; и теперь ты должен тратить своё и его время (а часто ещё и других участников проекта) на восстановление этих знаний.
Как документация помогает выйти в прод быстрее. Бонус — шаблоны, которые выручают в работе аналитика