Как да напиша добър документ за софтуерен дизайн

Като софтуерен инженер прекарвам много време в четене и писане на дизайнерски документи. След като преминах през стотици тези документи, видях от първа ръка силна връзка между добрите дизайнерски документи и крайния успех на проекта.

Тази статия е моят опит да опиша какво прави дизайнерския документ страхотен .

Статията е разделена на 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]подраздел тук, ако ETA на някои от тези важни събития се промени, така че заинтересованите страни да могат лесно да видят най-актуалните оценки.

Съществуващо решение

В допълнение към описанието на текущата реализация, вие също трябва да преминете през примерния поток на високо ниво, за да илюстрирате как потребителите взаимодействат с тази система и / или как данните преминават през нея.

А на потребителяисторияе чудесен начин да се формулира това. Имайте предвид, че вашата система може да има различни типове потребители с различни случаи на употреба.

Предложено решение

Някои хора наричат ​​това раздел Техническа архитектура . Отново опитайте да преминете през потребителска история, за да конкретизирате това. Чувствайте се свободни да включите много подраздели и диаграми.

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

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

Какво друго взехте предвид при излизането с решението по-горе? Какви са плюсовете и минусите на алтернативите? Обмисляли ли сте да закупите решение на трета страна - или да използвате такова с отворен код, което решава този проблем, вместо да създадете свой собствен?

Изпробваемост, наблюдение и предупреждение

Харесва ми да включвам този раздел, защото хората често се отнасят към това като домисъл или пропускат всичко заедно и почти винаги се връща, за да ги хапе по-късно, когато нещата се счупят и нямат представа как и защо.

Въздействие между екипите

Как ще се увеличи товаренето при повикване и разработки?

Колко пари ще струва?

Причинява ли някаква латентна регресия на системата?

Излага ли някакви уязвимости в сигурността?

Какви са някои негативни последици и странични ефекти?

Как екипът за поддръжка може да съобщи това на клиентите?

Отворени въпроси

Всички отворени въпроси, в които не сте сигурни, спорни решения, над които искате читателите да преценят, предложена бъдеща работа и т.н. Името на този език е „известни неизвестни“.

Подробен обхват и график

Този раздел ще бъде четен най-вече от инженерите, работещи по този проект, техническите ръководители и техните мениджъри. Следователно този раздел е в края на документа.

По същество това е разбивка на това как и кога планирате изпълнението на всяка част от проекта. Има много неща, които влизат в точното определяне на обхвата, така че можете да прочетете тази публикация, за да научите повече за обхвата.

Склонен съм също да третирам този раздел от документа за проектиране като текущо средство за проследяване на проектни задачи, така че актуализирам това, когато се промени оценката ми за обхват. Но това е по-скоро лично предпочитание.

Как да го напиша

Сега, когато говорихме за това, което влиза в един добър документ за дизайн, нека поговорим за стила на писане. Обещавам, че това е различно от вашия клас по английски в гимназията.

Пишете възможно най-просто

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

  • Прости думи
  • Кратки изречения
  • Водени списъци и / или номерирани списъци
  • Конкретни примери, като „Потребител Алис свързва банковата си сметка, след което ...“

Добавете много диаграми и диаграми

Диаграмите често могат да бъдат полезни за сравняване на няколко потенциални опции, а диаграмите обикновено се анализират по-лесно от текста. Имах късмет с Google Drawing за създаване на диаграми.

Професионален съвет: не забравяйте да добавите връзка към редактируемата версия на диаграмата под екранната снимка, за да можете лесно да я актуализирате по-късно, когато нещата неизбежно се променят.

Включете числа

Мащабът на проблема често определя решението. За да помогнете на рецензентите да разберат състоянието на света, включете реални числа като # от редовете в DB, ​​# на потребителските грешки, латентността - и как те се мащабират с използването. Спомняте ли си нотациите Big-O?

Опитайте се да бъдете забавни

Спецификацията не е академичен труд. Освен това хората обичат да четат забавни неща, така че това е добър начин да привлечете читателя. Не прекалявайте с това до степен да отнемете от основната идея.

Ако и вие като мен имате проблеми със забавата, Джоел Сполски ( очевидно известен със своите комедийни таланти ...) има този съвет:

Един от най-лесните начини да бъдеш забавен е да бъдеш конкретен, когато не е призован за [... Пример:] Вместо да казваш „специални интереси“, кажи „левичари от авакада“.

Направете Скептичен тест

Преди да изпратите своя документ за дизайн на други за преглед, вземете го, представяйки се за рецензент. Какви въпроси и съмнения може да имате относно този дизайн? След това се обърнете към тях превантивно.

Направете Ваканционен тест

Ако отидете на дълга ваканция сега без достъп до интернет, може ли някой от вашия екип да прочете документа и да го приложи по предназначение?

Основната цел на документа за дизайн не е споделянето на знания, но това е добър начин да оцените за яснота, така че другите да могат да ви дадат полезна обратна връзка.

Процес

А, да, страховитата P-дума . Документите за проектиране ви помагат да получите обратна връзка, преди да загубите куп време, прилагайки грешно решение или решение на грешен проблем. Има много изкуство за получаване на добри отзиви, но това е за по-късна статия. Засега нека просто да поговорим конкретно за това как да напишем документа за дизайн и да получим обратна връзка за него.

На първо място, всеки, който работи по проекта, трябва да бъде част от процеса на проектиране. Добре е, ако технологичният олово в крайна сметка води много от решенията, но всеки трябва да участва в дискусията и да влезе в дизайна. Така че „вие“ в тази статия е наистина множествено число „вие“, което включва всички хора в проекта.

На второ място, процесът на проектиране не означава, че се взирате в идеите за теоретизиране на бялата дъска. Чувствайте се свободни да замърсите ръцете си и да прототипирате потенциални решения. Това не е същото като да започнете да пишете производствен код за проекта, преди да напишете документ за дизайн. Не прави това. Но вие абсолютно трябва да се чувствате свободни да напишете някакъв хакерски код, за да потвърдите идеята. За да сте сигурни, че пишете само изследователски код, направете правило, че нито един от този прототип код не се обединява , за да се управлява .

След това, когато започнете да имате някаква идея как да предприемете проекта си, направете следното:

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

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

След това, след като сте написали груба чернова на вашия документ за дизайн, накарайте същия рецензент да го прочете отново и го подпечатайте, като добавите името си като рецензент в раздела за заглавие и хора на документа за дизайн. Това създава допълнителен стимул и отчетност за рецензента.

В тази бележка помислете за добавяне на специализирани рецензенти (като SRE и инженери по сигурността) за специфични аспекти на дизайна.

След като вие и рецензентът (ите) се отпишете, не се колебайте да изпратите документацията за дизайн на вашия екип за допълнителна обратна връзка и споделяне на знания. Предлагам да ограничите времето на този процес за събиране на обратна връзка до около 1 седмица, за да избегнете продължителни закъснения. Поемете ангажимент да адресирате всички въпроси и коментари, които хората оставят в рамките на тази седмица. Оставяне на коментари висящи = лоша карма.

И накрая, ако има много разногласия между вас, вашия рецензент и други инженери, които четат документацията, силно препоръчвам да консолидирате всички спорни точки в раздела за дискусии на вашия документ. След това организирайте среща с различните страни, за да говорите лично за тези разногласия.

Когато дискусионната нишка е повече от 5 коментара, преминаването към лична дискусия е много по-ефективно. Имайте предвид, че вие ​​все още носите отговорност за извършването на последното обаждане, дори ако всички не могат да стигнат до консенсус.

Разговаряйки наскоро с Шрей Банга за това, научих, че Quip има подобен процес, освен че освен опитен инженер или технически ръководител във вашия екип като рецензент, те също така предлагат инженер от друг екип да прегледа документацията. Не съм опитвал това, но със сигурност виждам, че това помага да се получат отзиви от хора с различни перспективи и да се подобри общата четливост на документа.

След като направите всичко по-горе, време да започнете изпълнението! За допълнителни точки на брауни, третирайте този документ за дизайн като жив документ, докато внедрявате дизайна . Актуализирайте документа всеки път, когато научите нещо, което ви кара да правите промени в оригиналното решение или актуализирате обхвата си. Ще ми благодарите по-късно, когато не се налага да обяснявате нещата отново и отново на всички заинтересовани страни.

И накрая, нека вземем наистина мета за секунда: Как да оценим успеха на дизайнерския документ?

Моят колега Кент Ракип има добър отговор на това: Документът за дизайн е успешен, ако е направена правилната възвръщаемост на инвестициите. Това означава, че успешният документ за проектиране всъщност може да доведе до резултат като този:

  1. Прекарвате 5 дни в писане на документа за дизайн, това ви принуждава да мислите през различни части на техническата архитектура
  2. Получавате обратна връзка от рецензенти, която Xе най-рисковата част от предложената архитектура
  3. Вие решавате да приложите Xпърво, за да намалите риска от проекта
  4. 3 дни по-късно разбирате, че Xили не е възможно, или е много по-трудно от първоначално предвиденото
  5. Решавате да спрете да работите по този проект и вместо това да приоритизирате друга работа

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

Моля, оставете коментар по-долу, ако имате въпроси или отзиви! Също така бих се радвал да чуя за това как правите проектиране на документи по различен начин във вашия екип.

Давайки кредит там, където се дължи кредит, научих много от горното, като работех заедно с някои невероятни инженери в Plaid (ние наемаме! Елате да проектирате и изградите някои сладки технически системи с нас) и Quora.

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