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

25

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

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

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

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

asthasr
источник
4
Решение Agile для этого является общение. Люди, ответственные за знание ЧТО, должны быть всегда доступны разработчикам для консультаций. Кроме того, вы должны пройти юнит-тесты и частый рефакторинг, чтобы держать под контролем "большой шарик грязи".
Эйфорическая
3
Я знаю, что у нас должны быть эти вещи. Мы не Я пытаюсь помочь нам в этом, и я пытаюсь создать надежную, воспроизводимую основу для коммуникации ( в конце концов, документы - это общение). Проблема в том, что прямо сейчас мы входим в тяжелую ситуацию: «Сделай это сейчас!» циклы, и мы полагаемся на специальное общение, которое приводит к тому, что у людей есть хранилища знаний, потому что нет никакой ссылки на реальную информацию о функции, которая появляется после пользовательской истории.
Asthasr
4
Agile не против документации - это против бесполезной документации. Пишите столько документации, сколько вам нужно, и не более. В частности, имейте в виду, что документация - это всего лишь ссылка на ментальную модель, которую вы (команда) используете в своих головах. Последнее действительно очень важно - однако, вы не сможете полностью его документировать. Вместо этого синхронизируйте его с помощью большого количества сообщений и запишите только достаточное количество ссылок на него, чтобы обеспечить согласованность модели в долгосрочной перспективе.
Петер Тёрёк
Я думаю, вы должны задать другой вопрос, чем этот. Для такого рода вопросов вы получите общие «документы в порядке, когда ...», которые вам не сильно помогут. Вы должны спросить, если ваше решение вашей проблемы является правильным и спросить о других возможных решениях.
Эйфорическая
4
«Agile не против документации - это против бесполезной документации.»: Каждый процесс разработки против бесполезной документации (согласно их определению полезной и бесполезной).
Джорджио

Ответы:

18

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

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

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

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

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

gbjbaanb
источник
Этот правительственный проект документа анекдот интересен, есть ли источник? Или просто то, что вы испытали воочию?
user145400
@ user145400 что-то, что я испытал :-(
gbjbaanb
13

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

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

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

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

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

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

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

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

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

  1. Сначала создайте временные проекты / модели, чтобы ваша команда смогла поговорить до написания кода. Не надейтесь сохранить их и не тратьте время на их оформление.
  2. Выпускать официальную проектную документацию можно только в том случае, если она кому-то понадобится (т. Е. Ваша команда действительно нуждается в организационной памяти)
  3. Создавайте проектную документацию только по коду, который был стабилизирован. Нет смысла пытаться задокументировать модуль, который постоянно меняется на каждой итерации.
  4. Подготовить проектную документацию, которая полностью описывает модуль (или часть продукта). В прошлом мы писали документы по дизайну, в которых документировались изменения, которые должны быть сделаны. Эти документы были совершенно бесполезны, как только релиз был сделан.
  5. Держите документ на очень высоком уровне. Если вы напишите 20 страниц, посвященных архитектуре и дизайну очень высокого уровня, этот документ а) будет фактически прочитан другими людьми и б) поможет людям ознакомиться с общим макетом вашего кода. За подробностями люди могут перейти прямо в код. Если вы напишите 700 страниц подробных спецификаций, они почти всегда не будут соответствовать действительности, это будет слишком много для всех, и вам придется поддерживать и обновлять 700 страниц вместо 20, когда будут внесены будущие изменения.
DXM
источник
То, что вы говорите, похоже на то, к чему я пытаюсь прийти; у нас сложный грязный ком, и я хочу простые документы, которые а) сообщают деловые намерения конкретной функции (то есть подробные пользовательские истории с ответами на вопросы); б) указать, какие части кода и существующие API будут затронуты; и c) рассматриваются как одноразовые артефакты, а не как нечто, что должно обновляться с каждой новой функцией навсегда. Сказать, что 20 страниц - это «высокий уровень», мне интересно - мы лишены даже этого. :)
asthasr
@syrion: Исходя из того, что вы только что сказали, звучит так, как будто вы хотите подробно описать каждую историю и создать документ с «пробелом в дизайне» (т.е. определить разницу между тем, что находится в коде сегодня, и тем, что будет в коде, как только история сделана). Есть ли у вас аудитория для таких документов? Исходя из моего опыта, я предсказываю, что никто их не прочтет. Разработчики, работающие над историей, уже знают, что нужно изменить (они либо написали документ, либо участвовали в первоначальном обсуждении). И если вы попытаетесь захватить ВСЕ детали изменений, которые вы собираетесь внести в историю, ...
ДХМ
... вы потратите больше времени на написание документации, чем на кодирование. И как только история закончена, как вы сказали, это разовые артефакты. Так зачем вам производить их в первую очередь?
ДХМ
потому что в настоящее время у нас есть среда, наполненная бункерами знаний. У нас есть люди, которые знают подсистему A, потому что они написали ее, и B, потому что они помогли поддержать ее, когда она в последний раз взорвалась, но никогда не касалась C, а D переписывался с тех пор. Новичкам и сторонним подрядчикам трудно войти или остаться в курсе событий.
Asthasr
@syrion: это действительно звучит так, как будто у тебя такая же потребность, как и у нас. Тем не менее, я озадачен, когда вы сказали, что хотите простые документы, которые ... рассматриваются как разовые артефакты. Допустим, у вас есть слой, который говорит с БД, и 6 историй, которые требуют изменений в этом слое. Планируете ли вы выпустить 6 разных документов вместе с каждой историей? Или вы хотите иметь единую спецификацию проекта для слоя БД? Тем не менее, единственная спецификация - это то, что должно быть обновлено с каждой функцией, которая касается уровня DB.
ДХМ
3

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

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

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

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

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

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

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

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

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

прецизионный самописец
источник
Этот ответ «правильный», но на самом деле не думает дальше. Как насчет архитектурного дизайна, например? А как насчет девелоперского / делового оборота? Как с этим справляются многие качественные юнит-тесты?
Пол
@Paul: Для новичков было бы неплохо иметь ОЧЕНЬ высокоуровневые архитектурные схемы, а также очень легкие стандарты кодирования. Я обнаружил, что хороший способ держать эти документы в актуальном состоянии - это держать их в вики и заставлять каждого новичка обновлять там, где они считают, что они датированы. Но этот вопрос был конкретно о предварительных проектных документах.
фунтовые
Я все еще поддерживаю то, что говорю. Измените архитектуру на то, что бизнес хочет назвать ее, и измените модульные тесты на регрессионные (автоматизированные?), И это применимо.
Пол
@Paul: Извините, я не следую. Какой полезный документ, по вашему мнению, я считаю плохим?
фунтовые
0

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

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

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

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

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

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

Карл Билефельдт
источник
0

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

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

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

Абстрактный класс
источник