Мифы об Agile. Миф №2: в Agile нет документации

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

Но мы должны тщательно обдумать это и понять:

• какую документацию нам действительно нужно производить, а какую нет;
• для какой цели и для какой аудитории действительно нужна документация;
• когда и как люди производят документацию.

Я думаю, что многие проекты Waterfall производят слишком много документации. Хорошо управляемый Agile-проект может предоставить нужное количество документации для нужной аудитории в нужное время и в нужном месте. Эта статья развеет миф о том, что в Agile-разработке программного обеспечения нет документации.

Типы документации (для Waterfall и Agile)

Во-первых, нам нужно различать два разных типа: пользовательская документация и внутренняя документация. Пользовательская документация создается как часть программного обеспечения и каким-то способом поставляется или предоставляется клиентам. Она рассказывает людям, как использовать продукт. Это может быть Руководство пользователя, интерактивная справка и т.д.

Документация для разработчиков не является частью продукта и не предоставляется клиентам. Это материалы, которые описывают, как или почему продукт был построен таким, какой он есть.

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

Эта статья о внутренней документации

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

Вопрос в том, насколько хорошо они документируют свои собственные системы с технической точки зрения. Однако многие люди обвиняют Agile-проекты в недостаточном количестве внутренней документации. Именно это я собираюсь обсудить здесь. Я полагаю, что:

• Многие Waterfall-проекты производят слишком много документации.
• В некоторых Agile-проектах недостаточно документации.
• Лучший вариант составить документацию – «в необходимом объеме, точно в срок».
• Информационные радиаторы предпочтительнее информационных холодильников.

Waterfall-проекты производят слишком много документации

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

Прежде всего, это экономическое обоснование, за которым быстро следует документ «Требования к бизнес-решениям», обычно очень большой, за которым быстро следует зловещий HLSD (проект решения высокого уровня). В который архитектор вложит свою кровь, пот и слезы.

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

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

Для чего были нужны все эти Waterfall-документы?

Эти документы были очень подробными и имели огромное количество дубликатов. Например, «Требования к бизнес-решениям» были более или менее продублированы в «Функциональной спецификации» и «Обзоре функциональной спецификации» (с разным уровнем детализации). Основной целью этих документов было попытаться:

• предотвратить изменения;
• уменьшить двусмысленность.

Ранее я утверждал, что подписи на самом деле не предотвращают изменения, и мы иногда не хотим разрешать любые изменения. Но помните, Agile говорит, что мы должны принять изменения (оговорюсь, мы должны, если эти изменения вызваны правильными причинами).

А что насчет уменьшения двусмысленности? Это, безусловно, хорошо, и это уменьшает «дефекты по спецификации». Т.е. какой-то элемент мы построили так, что он действительно соответствует спецификации, но при этом он дефектный, потому что он работает не так, как мы задумали. То есть у нас была плохая или неясная спецификация.

Но лучший способ уменьшить двусмысленность – это побудить людей к обсуждению, а не писать 50-страничный документ. Почему?

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

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

В некоторых Agile-проектах недостаточно документации

Давайте поднимем руки, если вы работали над Agile-проектом и не представили достаточно документации.

Может быть, ее было достаточно для вас, может быть, даже достаточно для ваших партнеров по команде. Но достаточно ли ее для бедной команды, которая должна поддерживать эту вещь через пару лет? Достаточно ли для консультантов, проводящих аудит НИОКР? Достаточно ли для инженера, пытающегося исправить ЧП на производстве в 3 часа ночи? Возможно нет. Давайте признаем, что это иногда случалось и пойдем дальше.

Некоторые Agile-проекты заходят слишком далеко. «Мы не обязаны писать или читать спецификации? Вау! Давайте просто начнем делать программу, и, может быть, кто-то что-то запишет позже». Бывает.

Но все мы должны помнить не только ту часть манифеста Agile, в которой говорится: «Работающий продукт важнее исчерпывающей документации», но и чуть ниже: «Не отрицая важности того, что справа (исчерпывающая документация), мы всё-таки больше ценим то, что слева (работающий продукт)». Нам важна документация, но не огромные груды ее. А сколько тогда?

Лучший вариант составить документацию – «в необходимом объеме, точно в срок»

В идеальном мире мы все подготовили бы нужный объем правильной документации в нужное время. Но это трудно. Это действительно трудно. Если у кого-нибудь есть секрет, пожалуйста, дайте мне знать.

Мудрый Agile-тренер однажды сказал мне: «Цель в том, чтобы создать достаточно документации. Не слишком много, не слишком мало, просто достаточно». Вы также можете применить концепции Lean – точно в срок (JIT) и отсрочка обязательств. Таким образом, вы откладываете производство документации до самой последней минуты, а не производите огромные объемы до того, как какая-либо работа будет выполнена. Почему?

• Документация, которая была произведена, но не потребляется, является типом потерь «излишние запасы» в Lean.
• Документация может стать чрезвычайно расточительной, если она создается до того, как будет построена система, а затем система изменится так, что документация станет неправильной (тип потерь «брак» в Lean).

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

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

Информационные радиаторы предпочтительнее информационных холодильников

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

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

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

Автор: Leon Tranter
Источник
Business photo created by freepik — www.freepik.com

Мифы об Agile. Миф №1: в Agile нет планирования

Книга в подарок

Опубликована наша книга «Прорыв. Единственный путь развития бизнеса». Это бизнес-роман о производственном предприятии, столкнувшимся с «потолком» в своем развитии. Для прорыва в развитии руководству и персоналу приходится преодолеть собственные, выстраданные на опыте, но устаревшие убеждения. Читателю предлагается пройти через этот прорыв вместе с героями. Вы увидите трудности такой трансформации, осознаете природу сопротивления изменениям и реальный путь к таким изменениям.
Подпишитесь на наш Telegram-канал и получите книгу в подарок!

Получить подарок

---

Лучшие статьи каждую среду в нашей рассылке. Присоединяйтесь к TOCpeople!

Подписаться

Нажимая на кнопку «Подписаться», я принимаю условия Политики конфиденциальности.