Чи повинен проектний документ містити обговорення плюсів та мінусів даної конструкції чи він повинен зосереджуватися на фактах та обґрунтуванні?

На даний момент я оновлюю проектний документ, щоб він був правильним та актуальним для майбутніх розробників.

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

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

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

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

Запитання:

• Якщо проектний документ повинен дотримуватися необґрунтованих фактів ("це дизайн") та обгрунтування ("ось чому це дизайн"), чи він також повинен використовуватися для вказівки на неповносправні проблеми з дизайном, які можуть бути проблематичними для майбутні розробники?
• Якщо проектний документ не повинен використовуватися для збору цієї інформації, який тип документа повинен захоплювати його, а що ще слід захоплювати, обговорюючи обґрунтування дизайну, компроміси та відомі проблеми (які не є дефектами, оскільки дефекти відслідковуються з використанням інших інструментів)?

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

Там, де я зараз працюю, зазвичай є окремий документ "Дизайнерські рішення" для відстеження всіх великих та важливих рішень. Часто форматується абзацом, що описує проблему (наприклад, "Деякі файли потрібно перемістити з сервера певним користувачам наприкінці кожного циклу обробки. Є багато способів зробити це ..."), таблиця зі стовпцями " опис рішення "(наприклад," переміщення файлів через FTP ")," профі "(такі як" Легко для користувачів керувати ")," мінуси "(наприклад," недостатньо безпечно для відповідності ABC-XYZ ") та висновок, що пояснює, чому було обрано конкретне рішення (наприклад, "FTP не буде використовуватися, оскільки воно не зможе відповідати певним вимогам дотримання"). У проектному документі зазвичай посилаються лише на обране рішення,

Якщо проектний документ повинен дотримуватися необґрунтованих фактів ("це дизайн") та обгрунтування ("ось чому це дизайн"), чи він також повинен використовуватися для вказівки на неповносправні проблеми з дизайном, які можуть бути проблематичними для майбутні розробники?

Це не "ні-чи".

Ніхто не читає документацію в першу чергу. Вони скупаються - у кращому випадку. Тому пишіть якомога менше документів. Один документ - це все, для кого є терпіння. Другий документ "без виходу" з "іншими питаннями" навряд чи буде прочитаний взагалі.

Переваги одного документа? Люди можуть її читати.

Недоліки одного документа? Мало хто. Здебільшого вона застаріла.

Переваги декількох документів? Жоден.

Недоліки декількох документів? Будь ласка, читайте про принцип DRY та грамотне програмування. Кілька документів означає безліч джерел помилок. Кожен документ не погоджується з іншим і не погоджується з кодом. Це досить очевидно. Це шлях божевілля.

Уникайте розтискання рук.

Документ «за» і «проти» може затягнутися у невизначені глибини дискусій про те, що робити, чи привабливо.

Якщо ви вважаєте, що потрібно представити плюси і мінуси, нехай це буде коротко і суттєво.

Зосередьтеся на тому, що є.

Зберігайте те, що не до голих кісток.

Якщо ви зробили орієнтири, дослідження або фактично дослідили альтернативи, документуйте це. Але якщо ви просто розглядаєте альтернативи, мінімізуйте їх.

Це не має бути вашою особистою історією судових процесів і страждань.

• Були проблеми? Виправлено? Взяли тижні? Дійсно боролися? Ледь цікавий анекдот. Це зафіксовано в коді. Попередні версії, неправильні версії, помилки та низькопродуктивні версії не мають значення. Вони в кращому випадку ведуть блог.

• У вас все ще є проблема? Не виправлено? Це означає, що є альтернативи. Задокументуйте це.

У процесі прийняття рішень є 3 важливі факти:

• Що було випробувано, а що не вийшло (і чому це не спрацювало, оскільки ви орієнтуєтесь на рухому ціль)
• Що
• Що може бути (просто чекаю на реалізацію X ...)

Однак, окрім "Що є", усі інші заплутають читача та завадять їй заробляти систему.

Мені подобається ідея захоплення інших 2, хоча вони менш цікаві для вивчення системи, вони можуть економити час при її зміні.

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

Так. Проектний документ повинен пояснювати переваги, ризики та припущення, пов'язані з описом проекту. Проектний документ має кілька цілей:

1. Запишіть дизайн так, щоб усі його розуміли, і щоб розуміння кожної людини не зникало з часом.

2. Донесіть проект нетехнічним людям, які працюють над проектом.

3. Допомога в плануванні, розподілі ресурсів, оцінці витрат та інших видах планування.

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

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

(Напевно, є й інші, але це хороший початок.)

Кожна з цих цілей добре служить доктором дизайну, який чітко пояснює, чому цей дизайн був обраний і які пов'язані з цим ризики:

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

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

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

4. Навіть коли ризик більше не є проблемою, часто корисно мати його документально, оскільки це може допомогти пояснити ситуацію в момент створення дизайну. Це може дозволити технічному обслуговувачу вирішити щось на кшталт: "Гаразд, вони зробили це ще тоді, тому що ... але це вже не проблема, тому я можу замінити цей код більш простим, швидшим виконанням". Те ж саме стосується пільг, звичайно.

5. Якщо ви працюєте над проектом для клієнта, то особливо важливо документувати ризики та вигоди. Це сповіщає клієнта про те, що за певних обставин все може піти не так або що запит на зміни дизайну може поставити під загрозу деякі обіцяні переваги.

Я вибираю з питання, що ви працюєте з існуючим дизайнерським документом для системи, яка вже була впроваджена. У цьому випадку багато можливих ризиків вже не є ризиками, тому не має сенсу намагатися документувати їх після факту. Однак тепер у вас є перевага заднього огляду, оскільки ви можете побачити частини оригінального дизайну, які вийшли не так добре. Думаю, вам слід: додати окремий розділ, який визначає поточні проблемні області та пропонує рішення (включаючи супутні ризики!); або створити окремий документ, який робить те саме. Цей новий розділ / документ може перетворитись на документ про розробку наступної версії програмного забезпечення.

Ось запис у блозі про написання дизайнерських документів, які можуть вам бути корисними.

Якщо існували вагомі причини уникнення більш очевидних або стандартних рішень, їх слід зазначити. Ви врятуєте комусь багато клопоту. Однак певна технологія може вдосконалюватися з часом, тому ваші причини можуть не застосовуватися. Потім майбутній розробник може використовувати власне судження.

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

Я особисто не ставлю це в проектний документ. Дизайн-документ повинен окреслити, як він є, а не навіщо.

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

Я погоджуюся з вами щодо обґрунтування в проектному документі.

У будь-якому випадку,

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

Так,

Я б додав обґрунтування лише щодо змін, які вносяться в конструкцію під час обслуговування.