Должен ли проектный документ содержать обсуждение плюсов / минусов данного дизайна или он должен быть сосредоточен на фактах и ​​обосновании?

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

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

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

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

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

Вопросов:

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

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

Там, где я сейчас работаю, обычно есть отдельный документ «Design decicions», чтобы отслеживать все важные и важные решения. Часто отформатированный с абзацем, описывающим проблему (например, «Некоторые файлы необходимо перенести с сервера определенным пользователям в конце каждого цикла обработки, есть много способов сделать это ...»), таблица со столбцами » описание решения »(например,« переместить файлы через FTP »),« плюсы »(например,« легко управлять пользователями »),« минусы »(например,« недостаточно безопасно для соответствия ABC-XYZ ») и заключение, что объясняет, почему было выбрано конкретное решение (например, «FTP не будет использоваться, поскольку он не сможет соответствовать определенным требованиям соответствия»). Проектный документ обычно ссылается только на выбранное решение,

Должен ли проектный документ придерживаться необработанных фактов («это дизайн») и обоснования («вот почему это дизайн») или его также следует использовать для указания на исправные проблемы с дизайном, которые могут быть проблематичными для будущие разработчики?

Это не «или-или».

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

Преимущества одного документа? Люди могут прочитать это.

Недостатки одного документа? Несколько. В основном это устаревает.

Преимущества нескольких документов? Никто.

Недостатки нескольких документов? Пожалуйста, ознакомьтесь с принципом СУХОГО и грамотного программирования. Несколько документов означает несколько источников ошибок. Каждый документ не согласен с другим и не согласен с кодом. Это довольно очевидно. Это путь безумия.

Избегайте заламывания рук.

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

Если вы чувствуете, что необходимо представить плюсы и минусы, сделайте это кратко и точно.

Сосредоточьтесь на том, что есть.

Держите то, что не до голых костей.

Если вы выполнили тесты, изучили или действительно изучили альтернативы, запишите это. Но если вы просто рассматриваете альтернативы, минимизируйте это.

Это не должно быть вашей личной историей суда и скорби.

• Была проблема? Починил это? Прошло несколько недель? Действительно боролись? Едва интересный анекдот. Это исправлено в коде. Предыдущие версии, неправильные версии, версии с ошибками и низкоэффективные версии не имеют значения. В лучшем случае они блог-фураж.

• Все еще есть проблемы? Не фиксированная? Это означает, что есть альтернативы. Документируйте это.

В процессе принятия решения есть 3 важных факта:

• Что было опробовано и не сработало (и почему это не сработало, потому что вы нацелены на движущуюся цель)
• Что
• Что может быть (просто ожидание реализации X ...)

Однако, кроме «Что есть», все остальные смущают читателя и мешают ей взламывать систему.

Мне нравится идея захвата двух других, хотя они менее интересны для изучения системы, они могут сэкономить время при ее изменении.

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

Да. Проектный документ должен объяснять преимущества, риски и предположения, связанные с описываемым дизайном. Проектный документ имеет несколько целей:

1. Запишите дизайн так, чтобы все его поняли, и чтобы понимание каждого человека не изменилось со временем.

2. Сообщите дизайн нетехническим людям, работающим над проектом.

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

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

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

(Возможно, есть и другие, но это хорошее начало.)

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

1. Очень важно, чтобы все в команде знали, каковы риски и преимущества, чтобы они могли работать вместе, чтобы избежать этих рисков и наилучшим образом использовать преимущества проекта.

2. Для нетехнических членов команды понимание рисков и выгод зачастую важнее, чем особенности самого проекта.

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

4. Даже когда риск больше не является проблемой, часто полезно документировать его, потому что он может помочь объяснить ситуацию во время создания проекта. Это может позволить сопровождающему решить что-то вроде: «Хорошо, тогда они сделали это так, потому что ... но это больше не проблема, поэтому я могу заменить этот код на более простую и быструю реализацию». То же самое касается выгод, конечно.

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

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

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

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

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

Я лично не включил бы это в проектную документацию. В проектном документе должно быть указано, как оно есть, а не почему.

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

Я согласен с вами по поводу обоснования в проектной документации.

Тем не мение,

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

Так,

Я бы вставил обоснование только об изменениях, которые вносятся в конструкцию во время обслуживания.