Проектная документация как часть Agile

На моем рабочем месте мы сталкиваемся с проблемой в том смысле, что «проворный» слишком часто означает «расплывчатые требования, плохие критерии принятия, удача!» Мы пытаемся решить эту проблему как общее улучшение.

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

Существует ли эффективный стандарт для этого?

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

"Неопределенные требования, плохие критерии принятия, удачи!"

да, это те же самые требования, которые вы предъявляете, даже если пытаетесь их зафиксировать! (Например, документ с требованием 10000, на создание которого у государственного клиента ушло 4 года, все еще был полон несоответствий, неопределенностей и даже внутренне противоречивых утверждений. Если документация с требованиями за 4 года не может дать вам достойного, точного требования, сделайте Вы когда-нибудь думали, что сможете получить что-нибудь нечеткое?)

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

Вы начинаете с вопроса «что вы хотите», а клиент отвечает «что-то вроде этого». Вы выполняете некоторую работу, а затем возвращаетесь к клиенту и говорите «это как то, что вы хотели?», А клиент обычно говорит «да, но ...», после чего вы спрашиваете «что вы хотите».

В конце концов вы получите именно то, что хотел клиент, даже если он не знает, что это такое! (черт, они никогда не знают, чего хотят, не совсем).

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

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

Во-вторых, я настоятельно рекомендую вам пересмотреть вопрос о разработке проектной документации после предварительной работы над историями. Мы пробовали это раньше, и это оказалось пустой тратой. В середине последнего релиза мы решили обновить документацию по дизайну ТОЛЬКО ПОСЛЕ кода для этой истории. И теперь я думаю, что это слишком рано.

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

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

Для удовлетворения (1) вам не нужно предъявлять фактический проектный документ. Ваша команда должна все еще иметь фазу проектирования до кодирования, но эта фаза может быть такой простой, как 15-минутная сессия перед доской или салфеткой. Вам не нужно создавать фактический документ, который займет часы (если не дни), чтобы написать только для обсуждения изменений дизайна.

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

Также имейте в виду, что каждый раз, когда член команды пишет / обновляет проектные документы, это время, когда код не пишется. Когда вы пишете документы перед реальным кодом, существует почти 100% вероятность того, что они потребуют обновления, потому что как только вы начинаете кодирование, дизайн всегда заканчивается изменением. И даже если вы пишете документы по дизайну после кода, как узнала наша команда, рефакторинг из последующих историй по-прежнему меняет дизайн.

Итак, что я бы порекомендовал:

1. Сначала создайте временные проекты / модели, чтобы ваша команда смогла поговорить до написания кода. Не надейтесь сохранить их и не тратьте время на их оформление.
2. Выпускать официальную проектную документацию можно только в том случае, если она кому-то понадобится (т. Е. Ваша команда действительно нуждается в организационной памяти)
3. Создавайте проектную документацию только по коду, который был стабилизирован. Нет смысла пытаться задокументировать модуль, который постоянно меняется на каждой итерации.
4. Подготовить проектную документацию, которая полностью описывает модуль (или часть продукта). В прошлом мы писали документы по дизайну, в которых документировались изменения, которые должны быть сделаны. Эти документы были совершенно бесполезны, как только релиз был сделан.
5. Держите документ на очень высоком уровне. Если вы напишите 20 страниц, посвященных архитектуре и дизайну очень высокого уровня, этот документ а) будет фактически прочитан другими людьми и б) поможет людям ознакомиться с общим макетом вашего кода. За подробностями люди могут перейти прямо в код. Если вы напишите 700 страниц подробных спецификаций, они почти всегда не будут соответствовать действительности, это будет слишком много для всех, и вам придется поддерживать и обновлять 700 страниц вместо 20, когда будут внесены будущие изменения.

Agile "мантра" не обходится без документации полностью.

Agile мантра предпочитает « Рабочее программное обеспечение, а не всеобъемлющую документацию ». Но обратите внимание на нижнюю часть манифеста.

То есть, хотя в пунктах справа есть значение, мы больше ценим элементы слева ».

У дяди Боба есть хорошая политика для документации

Не создавайте никаких документов, если это не нужно немедленно и важно .

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

С учетом всего сказанного, когда вы говорите: «В настоящее время мы сталкиваемся с ситуацией, когда новая функция может влиять на несколько областей в нашей системе« большой шарик грязи »», если вы собираетесь быть гибким, вам нужно что-то с этим сделать.

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

то есть. Сделайте потребность немедленной и значительной.

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

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

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

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

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

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

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

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

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