Як написати хороший документ з дизайну програмного забезпечення

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

Ця стаття - моя спроба описати, що робить проектний документ чудовим .

Стаття розділена на 4 розділи:

  • Навіщо писати проектний документ
  • Що включити в проектний документ
  • Як це написати
  • Процес навколо нього

Навіщо писати проектний документ?

Документ проекту - також відомий як технічна специфікація - це опис того, як ви плануєте вирішити проблему.

Уже є багато робіт про те, чому важливо написати проектний документ, перш ніж зануритися в кодування. Отже, все, що я тут скажу:

Проектний документ - найкорисніший інструмент для переконання у правильній роботі.

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

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

Чудово! Якщо ви все ще читаєте, ви вірите у важливість дизайнерських документів. Однак різні інженерні бригади і навіть інженери однієї команди часто пишуть проектні документи дуже по-різному. Тож давайте поговоримо про зміст, стиль та процес хорошого дизайнерського документа.

Що включити в проектний документ?

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

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

Назва та люди

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

Огляд

Підсумок високого рівня, який повинен зрозуміти кожен інженер компанії та використати його, щоб вирішити, чи корисно їм прочитати решту документації. Макс. 3 абзаци.

Контекст

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

Цілі та нецілі

Розділ "Цілі" повинен:

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

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

Віхи

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

Використовуйте календарні дати, щоб врахувати не пов’язані затримки, відпустки, зустрічі тощо. Це повинно виглядати приблизно так:

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

Додайте [Update]сюди підрозділ, якщо ЕТА деяких з цих етапів зміниться, щоб зацікавлені сторони могли легко бачити найсвіжіші оцінки.

Існуюче рішення

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

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

Запропоноване рішення

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

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

Альтернативні рішення

Що ще ви врахували, придумуючи рішення вище? Які плюси та мінуси альтернатив? Чи замислювались ви про придбання стороннього рішення - або використання рішення з відкритим кодом - яке вирішує цю проблему на відміну від створення власного?

Випробуваність, моніторинг та оповіщення

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

Взаємодія між командами

Як це збільшиться навантаженням на дзвінки та розробки?

Скільки грошей це коштуватиме?

Чи спричиняє це регресію латентності системи?

Чи виявляє це будь-які уразливості системи безпеки?

Які негативні наслідки та побічні ефекти?

Як команда підтримки може повідомити про це клієнтів?

Відкриті запитання

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

Детальний масштаб та хронологія

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

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

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

Як це написати

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

Пишіть якомога простіше

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

  • Прості слова
  • Короткі речення
  • Маркіровані списки та / або нумеровані списки
  • Конкретні приклади, наприклад, "Користувач Аліса підключає свій банківський рахунок, а потім ..."

Додайте безліч діаграм та діаграм

Діаграми часто можуть бути корисними для порівняння кількох потенційних варіантів, а діаграми, як правило, легше аналізувати, ніж текст. Мені пощастило з Google Drawing для створення діаграм.

Порада професіонала: не забудьте додати посилання на редаговану версію діаграми під скріншотом, щоб ви могли легко її оновлювати пізніше, коли щось неминуче зміниться.

Включіть цифри

Масштаб проблеми часто визначає її рішення. Щоб допомогти рецензентам зрозуміти стан світу, включіть реальні числа, такі як # рядки БД, кількість помилок користувача, затримка - і як вони масштабуються із використанням. Пам'ятаєте свої позначення Big-O?

Намагайся бути смішним

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

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

Один із найпростіших способів бути смішним - бути конкретним, коли до цього не вимагають [… Приклад:] Замість того, щоб говорити „особливі інтереси“, скажіть „ліворукі фермери авакадо“.

Зробіть тест на скептик

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

Зробіть тест на відпустку

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

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

Процес

Ах, так, страшне P-слово . Дизайнерські документи допомагають отримати зворотний зв’язок, перш ніж витратити купу часу на впровадження неправильного рішення чи вирішення неправильної проблеми. Існує багато мистецтва, щоб отримати хороші відгуки, але це для подальшої статті. На даний момент давайте просто поговоримо конкретно про те, як написати проектний документ та отримати відгук про нього.

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

По-друге, процес проектування не означає, що ви дивитесь на теоретичні ідеї дошки. Не соромтесь забруднювати руки та створювати прототипи потенційних рішень. Це не те саме, що почати писати виробничий код для проекту перед написанням дизайнерського документа. Не роби цього. Але ви абсолютно повинні почуватись вільно, щоб написати якийсь хакінський код для підтвердження ідеї. Щоб переконатися, що ви пишете лише дослідницький код, встановіть за правило, що жоден із цього коду прототипу не буде об’єднаний в майстер .

Після цього, коли ви починаєте уявляти, як реалізовувати свій проект, зробіть наступне:

  1. Попросіть досвідченого інженера або технічного керівника вашої команди стати вашим рецензентом. В ідеалі це був би хтось, хто добре поважається та / або знайомий з крайовими випадками проблеми. Підкупіть їх бобою, якщо це необхідно.
  2. Зайдіть у конференц-зал із дошкою.
  3. Опишіть проблему, з якою ви вирішуєте цього інженера (це дуже важливий крок, не пропускайте його!).
  4. Потім поясніть реалізацію, яку ви маєте на увазі, і переконайте їх, що це правильна річ для побудови.

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

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

Щодо цієї ноти, подумайте про додавання спеціалізованих рецензентів (таких як SRE та інженери з безпеки) для конкретних аспектів дизайну.

Як тільки ви та рецензент (и) вийдете, сміливо надсилайте проектну документацію своїй команді для отримання додаткових відгуків та обміну знаннями. Я пропоную обмежити час цього процесу збору відгуків приблизно на 1 тиждень, щоб уникнути тривалих затримок. Пообіцяйте вирішити всі питання та коментарі, які люди залишають протягом цього тижня. Залишення коментарів висить = погана карма.

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

Всякий раз, коли обговорення триває більше 5 коментарів, перехід до особистого обговорення, як правило, набагато ефективніший. Майте на увазі, що ви все ще несете відповідальність за здійснення останнього дзвінка, навіть якщо всі не можуть прийти до консенсусу.

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

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

Нарешті, давайте на секунду розберемо справді мета: як ми оцінюємо успіх дизайнерського документа?

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

  1. Ви витрачаєте 5 днів на написання документації з дизайну, це змушує вас продумати різні частини технічної архітектури
  2. Ви отримуєте відгук від рецензентів, що Xє найбільш ризикованою частиною запропонованої архітектури
  3. Ви вирішили реалізувати Xспочатку, щоб зменшити ризик проекту
  4. Через 3 дні ви зрозумієте, що Xце або неможливо, або набагато складніше, ніж ви задумали спочатку
  5. Ви вирішили припинити роботу над цим проектом і замість цього визначити пріоритет іншої роботи

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

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

Надаючи кредит там, де виплачується кредит, я дізнався багато з перерахованого вище, працюючи разом з неймовірними інженерами в Plaid (ми наймаємо! Приходьте, розробляйте і будуйте з нами якісні технічні системи) та Quora.

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