Project documentation is like sex ... | Agile тренинги, обучение и сертификации Scrum, Kanban, DevOps в Scrum Украина
The article is displayed in the original language.

Project documentation is like sex ...

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

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

Recommended events

Pavel Kamyshov, Misha Glushchenko  

Friends, we want to chat! Meeting at the trainings is great, but there is little room for improvisation, because there is a clear schedule that you need to follow. Therefore, we invite you to Lean Coffee!

Olaf lewitz  

This Certified Agile Leadership (CAL-1) course We want you to look for growth in new ways.

Jutta eckstein  

Learn Fast - Bottling Up: Workshop on the Essentials of BOSSA, Open Space, Sociocracy & Agile

Recommended articles

Начинаем LeSS трансформацию в Azer Turk Bank

Рады приветствовать нашего нового клиента - Azer Turk Bank, один из крупнейших банков Азербайджана.

За последние 2 года банк прошел большую организационную трансформацию, подготовив основу для начала адаптации диджитал продуктов. В свою очередь, мы помогаем запустить систему работы над …

Agile Gym на Agile Rock

Во время конференции 21-22 сентября у нас открывается Agile GYM.
Вы сможете не только прослушать доклады гостей на Agile Rock, но и прокачаться с коучами SCRUM Украина на личных коуч-сессиях.
Чувствуете, что нужны изменения в компании, есть запрос на обучение и не знаете что с этим делать?
На …

We are active on social networks and want to communicate. Add to our facebook page and join our communities.

For coaching and corporate programs:
+380 63 810-72-25 Evgeny
hello@scrum.ua

For public classes, registrations, accounts:
097 756-6757 Anastasia
backoffice@scrum.ua

For all phone numbers - voice, sms, viber, whatsapp.

©2017 - 2019 Scrum Ukraine. All rights reserved.