Представляю вам моих друзей - Джейн и Джона. Джон долгое время работает аналитиком в большой компании и отвечает за выявление требований в новых и существующих продуктах. Джон использует спецификации программного обеспечения в качестве рабочего инструмента, чтобы записывать все требования клиента, которые необходимо разрабатывать или поддерживать. Джейн - разработчик в той же компании. Обычно она получает от Джона спецификацию и начинает технический анализ и дизайн того, что необходимо разработать. Когда этот анализ выполнен, она пишет код. И Джон, и Джейн передают требования и документацию по дизайну на утверждение: Джон перед тем, как передать спецификации Джейн, а Джейн перед тем, как начать кодинг. Недавно компания, где трудятся Джон и Джейн, внедрила гибкие методологии управления проектами и разработки ПО, и все изменилось. Больше нет огромных предварительных требований и дизайна: и спецификации, и разработка разбиваются на малые куски информации, а огромные текстовые документы, которыми пользовались годами, куда-то исчезли. Изменился и способ написания кода, и всякое другое, вроде теста дизайна до внедрения, и именование переменных длинными именами стали поощрять. Вполне ожидаемо, что перед Джоном и Джейн встало множество вопросов:

• Как начинать разработку, если мы не знаем точно, что разрабытываем?
• Куда мы записываем функциональные данные, если не в привычные спецификации?
• Как мы узнаем все детали того, что надо разработать?
• Где мы документируем спецификации и код для последующей поддержки?
• Когда мы документируем, если фазы документации нет?

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

Документирование и гибкий склад ума

«Манифест Agile» гласит, что мы ценим:

Людей и взаимодействия превыше процессов и инструментов

Рабочее ПО превыше всеобъемлющей документации

Сотрудничество с заказчиком превыше переговоров по контракту

Реакцию на изменения превыше следования плану

Хоть документация тут и упомянута, принципы Agile не дают никаких четких директив о том, как документировать. Потому рассмотрим, что вообще ожидается в плане документации в Agile-проекте?

Принципы, которые лежат в основе гибкого мышления, сфокусированы на создании ценности для клиента. Это значит, что время, которое мы тратим на проект, должно быть направлено на то, что имеет ценность для заказчика, и как можно меньше - на то, что ценности не несет. Это относится и к документации. В типичной каскадной модели документирование - это предопределенная фаза, которая отнимает массу времени. Переход к Agile означает, что нам надо переосмыслить способ документирования, дабы избежать траты времени на то, ценность чего сомнительна. Значит ли это, что документировать вообще не надо? Вовсе нет.

Другой принцип в основе Agile - адаптация к изменениям. Это значит, что мы не планируем, забегая слишком далеко вперед, потому что на протяжении проекта многое может измениться. Поэтому основной фокус всегда на текущем планировании. Это применимо и к документации. Чтобы избежать ненужных трат времени, документация в Agile должна создаваться, только когда это необходимо. Но как узнать, когда это необходимо?

ПОЧЕМУ документировать, или Вам действительно это нужно?

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

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

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

• Для чего нужна эта документация? Для поддержки разработки? В качестве функционального справочника?
• Кто за целевая аудитория у этой документации? Какой именно человек? Какой отдел? Или это заказчик? Или будущие команды поддержки?
• Как целевая аудитория будет использовать данную документацию? Как справочник? Как руководство?
• Сколько стоит создание данной документации? Сколько времени займет ее создание? Кто это будет делать?

Ключ к решению, нужна документация или нет, в определении «необходимой и достаточной» документации. Найдите баланс между тем, что действительно нужно ключевым лицам, и именно это и сделайте. Не более и не менее. «Необходимое и достаточное».

Что, где и когда документировать

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

Что

Уточните у целевой аудитории, что за документацию вы будете создавать. Учебники? Методички? Руководство по эксплуатации? Описание бизнес-правил? Описание системы? Чтобы решить, что документировать, определите, какая техническая и функциональная информация будет произведена на каждой стадии проекта:

• Какая документация понадобится перед началом проекта?
• Какая документация понадобится во время проекта?
• Какая документация понадобится, когда продукт будет разработан и выпущен?

Где

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

Когда

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

Как документировать

К этому моменту мы уже должны были решить:

• какая документация будет необходимой и достаточной
• что это будет
• где это будет храниться и как будет доступно
• когда будет создаваться

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

Стартовая документация

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

Проектная документация

Во время проекта, пока продукт пошагово разрабатывается, могут создаваться два вида документации:

• A. Необходимые и достаточные требования – как часть бэклога
• B. Внедренные системные и бизнес-правила - на выходе каждого спринта

У каждой документации есть собственная целевая аудитория:

• A - команда
• B - заинтересованные лица и команда техподдержки.

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

Функциональная документация

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

• Описание: «Я, <роль пользователя>, хочу <действие>, чтобы <описание ценности, которую это действие несет для заказчика>
• Критерии приемки: критерии, согласованные между командой и владельцем продукта, по которым можно будет определить, что история завершена.

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

Таким образом, тут должна быть необходимая и достаточная информация для целевой аудитории А. По мере реализации пользовательской истории команда может решить, что нужны новые критерии приемки, которые добавляются в пользовательскую историю. Помните, что в Agile пользовательские истории не предназначены для отражения исчерпывающей и детальной информации, а, скорее, призваны давать основные направления, что должно быть внедрено, в расчете на будущее сотрудничество между владельцем продукта и командой в плане подробностей. Когда пользовательская история внедрена и принята заинтересованными лицами, она считается выполненной. В этот момент ее надо перенести из бэклога в спринт.

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

Техническая документация

Во время разработки программисты должны использовать общепринятые передовые практики, являющиеся частью методологии Agile, такие, как TDD (Test-Driven Development - разработка через тестирование) и BDD (Behavior-Driven Development - разработка через реализацию поведения), а также писать хорошо структурированный код, который смогут читать и не технические специалисты. Следовательно, должна быть техническая документация, описывающая код. Актуальная функциональная и техническая документация.

Поскольку код - это наиболее надежный источник актуальных реализованных бизнес- и системных правил, лучший способ хранить полезную документацию - это разместить ее непосредственно в коде. Один из способов сделать это - внедрение динамической документации. Динамическая документация - это такая документация, которая постоянно редактируется и обновляется. Концепция динамического документа опирается на интеграцию документа, написанного на специфическом для домена языке (как, например, Gherkin используется в Cucumber), в код согласно критериям приемки.

При использовании инструментов, облегчающих непрерывную сборку динамической документации, критерии приемки, указанные в пользовательских историях, внедряются как часть кода и выводятся в читаемом формате в обновляемом хранилище (обычно онлайн). Вот некоторые инструменты, поддерживающие механизм динамической документации: Cucumber, Concordion,FitNesse, SpecFlow, Pickles. Имеет смысл взглянуть на них.

Постпроектная документация

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

Подводя итоги

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

Для многих переход от каскадной модели к гибкой разработке так же сложен, как для моих воображаемых друзей Джейн и Джона. Эти перемены в способе, который работал десятилетиями, вызывают множество вопросов и сомнений. Среди других возникающих от этого перехода (и особенно изменения способа мышления) вопросов, документация - одна из самых больших проблем, так как изменения затронули ее сильнее всего - от документирования всего подряд еще до начала разработки до почти полного отсутствия документации на тех же самых этапах. Agile вовсе не стоит за то, чтобы не писать документацию вообще. Но эта методика напоминает командам, что фокус всегда должен быть на создании ценности для заказчика. В процессе написании документации этот ключевой принцип необходимо брать в расчет. Поэтому, документируя, держите в уме делать это не более и не менее, чем необходимо, и лишь тогда, когда необходимо.

Оригинал: http://www.infoq.com/articles/roadmap-agile-documentation

Об авторе:

Начав карьеру в качестве разработчика и системного аналитика почти 20 лет назад, Эстер Гонсалес в последние 4 года решила изучать деловую сторону IT. Работая IT-бизнес аналитиком в Agile-командах, она стала энтузиастом Agile, и теперь исследует методологии Agile, техники системного и бизнес-анализа, пишет статьи в блоги и издания, выступает на конференциях и вдохновляет все это улучшать.

Перевод: Александра Родсет

Сертифицированные курсы

Андрей Плетенев. Онлайн курс Agile. SCRUM. Курс включает более 20 уроков с практическими заданиями, которые индивидуально проверяются и комментируются тренером.

Еще интересные статьи на эту тему:

• Критерии приёмки для требований в Agile
• Дисциплинированная гибкая поставка - Disciplined Agile Delivery
• 5 причин использовать Story Mapping в вашем следующем проекте
• Оценка трудоемкости при планировании релиза в Agile
• Подгруппы Agile раскрывают потенциал команды