Project documentation is like sex ... | Scrum Україна - тренінги, навчання та сертифікації Agile, Scrum, Large-Scale Scrum
 
Стаття відображається оригінальною мовою.

Project documentation is like sex ...

Проектная документация, как секс... И в этом посте мы расскажем вам о прагматичном способе её ведения, который по-настоящему работает.

27 июл 2019

Alt Text

Мифы о документации

И скажу вам такую вещь - есть два подхода к проектной документации:

  1. безумный
  2. здравый

Безумный заключается в вере в то, что документация - должна быть 100% актуальна, что её никогда не будут вести разработчики, потому что у них на это нет времени и ещё много всяких небылиц.

Вот четыре главных мифа о документации, которые мешают её вести.

Миф первый - документация должна быть идеальной, детальной и актуальной

Тут всё понятно, сторонники этого мифа не смотря на суровую реальность, которая режет их веру острым ножом, просто уверены в том, что документацию нужно ввести так же внимательно, как писать код - хранить версии в репозитории, проводить ревью, обновлять устаревающие диаграммы и т.п. Чепуха!

Документация никогда не будет идеальной. Всегда будет неполной и устаревшей. И это ОК! Она - не модель мира, она - некий срез нашего понимания.

Миф второй - нам нужно завести тех писателя

Соответственно, сторонники первого мифа, которые не смотря на свои попытки навязать своё (идеалистичное) мировоззрение быстро убеждаются в том, что разработчики просто неспособны удовлетворить их (безумным) требованиям. И они ищут спасения у ... о господи! - у отдельно нанятых на эту работу специалистов. Ну, или чтобы не тратиться - "давайте отдадим эту работу джуниорам!"

Дёшево и сердито. Только пользы - ноль.

Документирование нужно сделать частью процесса разработки, тогда оно будет не только существовать, но и приносить пользу!

Миф третий - у нас вообще нет документации

Документация есть всегда.

Бэклог - чем это не документация?

Какая ни есть - а документаций всё-таки.

Тесты - разве это не документация?

И к тому же исполняемая!

Код - ведь документации же?

К тому же актуальна всегда и на все 100%.

Так что, документация у вас есть. Можете расслабиться.

Миф четвёртый - документация не дружит с гибкой разработкой

А вот это - миф мифов. Но тут важно понять что есть два метода работы с документацией, и один из них и правда не совместим с принципами гибкой разработки и со здравым смыслом в принципе.

  1. Документация, которая готовится отдельно и высылается для ознакомления.
  2. Документация, которая составлена по факту общения и является напоминаем бизнес правил и всевозможных договорённостей.

Угадайте какой их этих двух методов не совместим с Agile? Конечно же - первый.

И к тому же он приводит к избыточной документации (ведь пишущий документацию не знает, что нужно будет знать читающему документацию и старается что мочи), а чем больше в докумененте информации - тем быстрее он устаревает.

Значит, её нужно чаще обновлять. Но пишущий не знает, что стоит обновить и на чем стоит акцентировать внимание. И так далее. Это замкнутый, порочный круг, который приводит к трате времени и дискредитации самого процесса документирования.

Alt Text

Принципы прагматичной документации

Поделюсь кратко и сжато хорошими и прагматичными практиками работы с документацией, которые не заводят в тупик, а позволяют извлечь пользу.

Они очень просты, даже очевидны. Но почему же так мало команд ими пользуется?

Одна спецификации на бизнес фичу (вместо спецификации на каждую user story)

Самый большой минус техники user stories в том, что за ними теряется "big picture" - что нужно сделать понятно, а вот зачем и как оно лепится вместе - нет.

Важно понимать: user stories - это техника планирования, а не документирования требований.

Так что возлагать надежду на них, как на документацию не стоит. Или же они станут перегруженными текстом и диаграммами, при чём дублирующимся между собой. А это их сделает большими и неподъёмными для реализации в коротких спринтах. То есть будет противоречить хорошим практикам user stories - простоте, независимости и атомарности.

  • Боже, что же нам делать? - спросите вы.
  • Лопухи, ведите всю документацию об одной цельной бизнес фиче в одном документе, - услышите вы голос свыше.

Так и стоит делать: независимо от того, на сколько историй побита бизнес фича - вся документация о ней (большая картина, бизнес правила, договорённости, упрощения, диаграммы и т.д.) - всё это должно быть в одном... чуть не сказал "в одном месте".

Нет! Это раньше у вас была документация в одном месте, теперь же она - в одном документе! Или на одной странице, в случае wiki. При чём таких страниц-документов может быть сколько-угодно, но по одной на фичу.

Всегда начинайте с бОльшей картины - "зачем и почему" (вместо технических решений)

Этот совет - не сюрприз, и не находка. Но важен как божий свет - начинайте любой документ бизнес фичи с того, зачем она нужна бизнесу (и пользователям).

Это vision фичи. И потому логично, что его должен готовить продуктовод (Product Owner) - это его вводные в работу над фичей. Возможно - единственные вводные от него. Но самые главные, так как описывают мотивацию к работе над фичей - мотивацию инвестирования в фичу.

Если вы хотите бОльшей структуры вижина фичи - то вот важные элементы:

  1. ТЕКУЩАЯ СИТУАЦИЯ - как выглядит стартовая позиция этой инициативы, когда фичи ещё нет.
  2. ПОЛЬЗА ДЛЯ БИЗНЕСА - как эта инициатива (появление бизнес фичи) повлияет на бизнес.
  3. ГРАНИЦЫ - что не входит в эту инициативу.
  4. ГИПОТЕЗЫ - на чём базируется наша вера в то, что эта бизнес фича будет полезна.
  5. МЕТРИКИ УСПЕХА - как мы узнаем, что эта фича приносит обещанную пользу бизнесу?

Хотите ещё больше структуры? Посмотрите тут.. Но не переборщайте.

Растите документ по мере проработки фичи (вместо того, чтобы писать спецификации ДО начала работы)

Если вводная часть (мотивация) - это вводные от продуктоводов, то самое мясо - бизнес правила, примеры вычислений и примеры поведения пользователей - это вводные от экспертов предметной области (SME - subject matter expert). Но как их знания документируются?

А очень просто - эти люди приглашаются на сессии проработки бэклога (или очередной бизнес фичи) и учат команды своему домену. Основные тезисы записываются в документ по ходу - как summary этой совместной работы. Таким образом документация наращивается и наполняется смыслом.

Если вы усвоили этот урок - можете больше не переживать о качестве вашей документации никогда.

Документируйте общее понимание (вместо того, чтобы писать сочинение на тему)

Таким образом, документация становится напоминанием о договорённостях и уроках от представителях бизнеса, а не тонной букв спущенных сверху. Это единственный верный путь.

Важно понимать, что если люди совместно не проговорили суть, то две модели мира в голове у пишущего и в голове у читающего будут разными! И как следствие - сделанная работа не будет соответствовать предполагаемой. А значит - польза от документации нулевая.

Польза от документации - это количество переработки, которые она помогла предотвратить.

Поэтому сначала "эти двое" должны собраться у доски и договориться о модели мира, а потом уже её описать. Тогда описание будет служить напоминанием о сути их разговора и поможет в будущем тому, кто будет реализовывать фичу, сделать её согласно обсуждённой модели.

Запомните мантру бизнес анализа - сначала договариваемся, потом записываем. Никак не наоборот.

Вставляйте фотографии досок или флипчартов (и тратьте время на их цифровую отрисовку)

Соответственно, документация не должна быть красивой и аккуратной. Она должна помогать вспомнить контекст, суть договорённостей и полученной информации.

И так как мы (люди) лучше запоминаем графически, всякого рода фотографии каракулей на досках будут очень кстати, особенно когда мы только какое-то время спустя будем читать спецификацию фичи и пытаться восстановить картинку мира.

Поэтому НЕ заменяйте фотографии живых артефактов красивенькими рисунками! А если у вас есть тяга всё-таки прихорошить спеку, да и так чтобы её могли прочесть и понять те, кто, увы, не был у доски, не прорабатывал фичу и поэтому не разбирает каракули, добавляйте красивые рисунки ПОД фотографим досок, а не заменяйте их.

Вписывайте вопросы (вопросы не менее важнее ответов)

Дык. Очевидно. Вписывайте в доку открытые вопросы. Это поможет вам знать, как продолжать начатые дискуссии по теме данной фичи.

Используйте таблицы примеров (вместо длинного текста)

Что может быть лучше полезного текста? Структурированный полезный текст.

Техника "Specification by Example" - лучшее решение.

Практически любые детали бизнес требований можно описать в виде примеров. И каждый пример - это строка таблицы. Колонки - атрибуты или параметры, которые могут меняться, чтобы показать поведение в разных условиях.

Используйте бесплатные инструменты одновременного редактирования (вместо Confluence)

Если Jira - это то место, где умирают user stories. То Confluence - это то, откуда исходит запах.

Самый сильный минус большинства wiki-подобных инструментов - невозможность одновременного редактирования одного и того же текста. И за такие продукты ещё нужно платить!

Берите Google Drive (или его аналоги), и вы сможете не только распараллеливать митинги по проработке бэклога (подгруппы смогут писать одновременно в документ), но и проводить эти сессии с удалёнными участниками или командами. Тройная выгода.

Начинайте разработку сразу по мере прояснения первых деталей (не ждите, пока расступится весь туман, этого никогда не произойдёт!)

Да, да и да. Начинайте проработку бизнес фичи с того, что известно, понятно или легко узнаваемо. И из этой части фичи тут же нарезайте атомарные истории, которые добавляйте в бэклог и пускайте в разработку.

По мере разработки более понятных частей бизнес фичи будут проясняться менее ясные и самые тёмные её стороны.

Это и есть суть Agile в применении к бизнес анализу. Если такая вещь, как бизнес анализ вообще существует. В чём я лично очень сомневаюсь.

Alt Text

Рекомендовані заходи

тренінг
Олексій Кривицький  

Це офіційний інтенсивний сертифікаційний клас Scrum Alliance. Курс читає Олексій Кривицький – Certified Scrum Trainer, розробник, скрам-майстер та практикуючий agile-коуч з 2008 року.

тренінг
Олексій Кривицький  

Це офіційний інтенсивний сертифікаційний клас Scrum Alliance. Курс читає Олексій Кривицький – Certified Scrum Trainer, розробник, скрам-майстер та практикуючий agile-коуч з 2008 року.

тренінг
Дмитро Незабитовський  

Дводенний курс з основ Agile, Scrum фреймворку та Kanban-методу. Курс сертифікаційний, після закінчення учасники отримують іменні сертифікати ICAgile Certified Professional (ICP): Scrum & Kanban.

Рекомендовані статті

Скільки коштують ваші зустрічі? Та як не втрачати гроші.

Зустрічі у компаніях, які займаються розробкою програмного забезпечення, часто визнаються найважливішою складовою успішного продукту (чи проєкту). Однак, їх вартість і вплив на бізнес часто залишаються недооціненими. Проведення зустрічей вимагає великих витрат часу і ресурсів, і саме тому …

Top 5 питань про Agile Retrospectives

Я проводжу ретроспективи досить часто, близько сотні на рік, а почав уперше це робити майже 10 років тому. У цій статті я хочу відповісти на Top 5 із питань про Ретроспективи, які найчастіше задають учасники тренінгів та Agile-ком'юніті.

Чому коучинговий підхід актуальний у бізнесі?

Однією з основних функцій сучасного менеджера лідера є розкриття потенціалу кожного учасника команди для досягнення максимальної ефективності та реалізації цілей. Scrum Masters, Product Owners, Facilitators та інші лідери й керівники можуть використовувати коучинговий підхід для підвищення …

Ми активні в соціальних мережах і хочемо спілкуватися. Додавайтеся на нашу сторінку в facebook та приєднуйтесь до наших спільнот.

З приводу тренінгів, реєстрацій, рахунків:
+380993383636
@scrum_ukraine
hello@scrum.ua

Із питань корпоративних програм:
+380993383636
hello@scrum.ua

©2017 - 2024 Scrum Ukraine. Всі права захищені.

Політика конфіденційності