Как эффективный способ записать обоснования решений о дизайне продукта?

В нашей компании мы не используем какие-либо проектные документы. У нас всего три сотрудника, поэтому все обсуждения дизайна продукта происходят лично или в Slack. (Мы также работаем над базовым пакетом Slack, который позволяет просматривать только самые последние сообщения.)

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

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

Как мы можем эффективно записать обоснования проектных решений?

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

Чтобы быть на 100% ясным: я не говорю о дизайне кода. Я говорю о дизайне продукта, который реализуется кодом. Другими словами, я не говорю о таких решениях, как «должны ли мы структурировать этот класс, используя композицию, а не множественное наследование?»; Я говорю о таких решениях, как «мы должны требовать от пользователя подтвердить свой адрес электронной почты, прежде чем войти в систему?».

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

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

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

ИМХО проектные документы могут иметь свою ценность, но если они описывают вещи слишком «далеко» от предмета, который они описывают, они имеют тенденцию очень быстро становиться противоречивыми. Поэтому я рекомендую размещать любую проектную документацию как можно ближе к проектируемому элементу.

Используйте отдельные документы только в том случае, если вы хотите документировать проектные решения, которые затрагивают множество различных мест вашего кода сквозным образом. Когда вы используете их, попробуйте сделать их частью вашей кодовой базы и разместить их на соответствующем уровне иерархии проектируемого объекта (поэтому, если вы принимаете проектное решение для одного модуля, который состоит из множества файлов исходного кода, поместите описание проекта ». внутри "этого модуля, но не в одном файле класса, не в" описании верхнего уровня ", которое действительно для других модулей, и определенно не в отдельной вики вне вашей SCCS. Если вы хотите записать какой-то" высокий уровень ", продукт общие решения дизайна, тогда документ высшего уровня может быть лучшим местом, но удостоверьтесь, что этот документ остается на том уровне абстракции.

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

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

Теперь у вас есть проблема. Вы обнаруживаете, что sqiushyware не достаточно хорошо обосновывает. Хорошо, что вы поняли, что есть проблема, и определили, что ее нужно решить! Это не всегда легкий шаг! Таким образом, мы уверены, что решение состоит в том, чтобы перенести часть этого обоснования в документацию. Однако этого недостаточно. Мы никогда не сможем забыть вторую половину головоломки, которая заключается в повторной загрузке логического обоснования в сквош-ПО, когда вам нужно принять решение. Я видел множество команд, которые документируют все как сумасшедшие, но контент на самом деле не организован, чтобы помогать принимать правильные решения, поэтому они в конечном итоге забывают обоснования, даже если они записаны .

Итак, у вас есть два этапа. Вы должны получить обоснование из squishyware и в документацию. Затем вам нужно убедиться, что документация организована достаточно хорошо, чтобы вернуть рациональное обратно в squishyware, когда вам это нужно! Теперь я думаю, что у нас достаточно постановки проблемы, чтобы понять, какие задачи понравятся. Когда вы документируете, вы, как правило, не знаете, кто будет смотреть на это позже или что они ищут. Аналогично, когда вы просматриваете документацию, вы, как правило, не знаете, что ищете (в лучшем случае вы можете знать, когда).

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

Время идти проворным.

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

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

• Принимаем ненадежные форматы документации. Ничто не будет правильным с первого раза. Лучше получить данные и выяснить, как сделать их надежными позже. Например, вы можете задокументировать свои обоснования в блоке <rationale> </ rationale> или в чем-то подобном, что упростит сбор этих данных позже. Сохранение логических обоснований в пользовательской истории пока просто отлично!
• Никогда не забывайте ценность организации. Узнайте, как вам, как команде, нравится искать обоснования в документации, и попробуйте документировать это. У каждой команды будет свой процесс. В одной из моих команд мы никогда не могли найти билет, на котором было обоснование. Что мы могли бы сделать, так это найти строку кода, которая имела значение, сделать, svn blameчтобы узнать, когда она изменилась и почему, а затем пойти посмотреть на билеты. Как только мы были там, мы обычно помещали все необходимое объяснение прямо в билет. Это только сработало для нас, узнайте, что работает для вас.
• Органическая документация может расти со временем. Разработчики редко знают, какие обоснования являются наиболее важными в тот день, когда им нужно было это написать. Обычно мы узнаем, какие из них были важны позже. Если у вас есть процесс подготовки документации, которая позволяет разработчикам управлять своим собственным небольшим набором обоснований, важные из них поднимутся на поверхность. Что еще более важно, обоснования могут измениться. Возможно, вы понимаете, что два разных изменения с двумя разными обоснованиями действительно лучше всего описываются одним обоснованием, которое работает для обоих. Теперь между вами и решениями стало меньше контента!

Я бы предложил создать частный экземпляр MediaWiki или аналогичного программного обеспечения вики. Там действительно легко организовать и реорганизовать контент, и вы можете копировать и вставлять новые обсуждения прямо на вкладку обсуждения соответствующей статьи (статей) вики. Мы использовали MediaWiki на моей последней работе для всех наших документов по архитектуре и API, и это спасало меня.

Подумайте об этом с точки зрения кодера, которого попросят изменить его через 12 месяцев.

Если вы добавите это бизнес-правило в качестве автоматизированного теста, тогда будут внесены изменения, И ТОГДА вы получите из-за неудачного теста противоречивое требование (и, надеюсь, вы поймете человека, связанного с первоначальным требованием, и его причину для его указания).

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

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

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

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

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

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