de Angela Zhang
Ca un inginer de software, mi-am petrecut o mulțime de timp de citire și scriere documente de proiectare. După ce a trecut prin sute de aceste documente, am văzut prima mana o corelație puternică între documente de design bun și succesul final al proiectului.
Acest articol este încercarea mea de a descrie ceea ce face un document de design mare.,
articolul este împărțit în 4 secțiuni:
- de Ce scrie un document de design
- Ce să includ într-un document de design
- Cum să-l scrie
- procesul jurul ei
de Ce scrie un design document?
un document de proiectare-cunoscut și sub denumirea de specificații tehnice — este o descriere a modului în care intenționați să rezolvați o problemă.
există deja o mulțime de scrieri despre motivul pentru care este important să scrieți un document de design înainte de a vă scufunda în codificare. Deci, tot ce voi spune aici este:
un document de design este cel mai util instrument pentru a vă asigura că lucrarea potrivită este finalizată.,scopul principal al unui document de design este de a te face mai eficient, forțându-te să gândești prin design și să aduni feedback de la alții. Oamenii de multe ori cred că punctul de un doc de proiectare este de a învăța pe alții despre unele sistem sau servi ca documentație mai târziu. În timp ce acestea pot fi efecte secundare benefice, ele nu sunt scopul în sine.ca regulă generală, dacă lucrați la un proiect care ar putea dura 1 lună de inginer sau mai mult, ar trebui să scrieți un document de proiectare. Dar nu te opri aici — o mulțime de proiecte mai mici ar putea beneficia și de un mini design doc.
minunat!, Dacă încă citiți, credeți în importanța documentelor de proiectare. Cu toate acestea, diferite echipe de inginerie, și chiar ingineri din cadrul aceleiași echipe, scriu adesea documente de proiectare foarte diferit. Deci, să vorbim despre conținutul, stilul și procesul unui document de design bun.
de Ce să includeți într-un design doc?
un document de proiectare descrie soluția unei probleme. Deoarece natura fiecărei probleme este diferită, în mod natural, doriți să vă structurați documentul de proiectare diferit.,
Pentru a începe, următoarele este o listă de secțiuni pe care ar trebui cel puțin să ia în considerare, inclusiv în următoarea design doc:
Titlu și Oameni
titlul de design doc, autor(i) (ar trebui să fie aceeași ca la lista de persoane de planificare pentru a lucra la acest proiect), referent(s) din doc (vom vorbi mai mult despre faptul că, în Procesul secțiunea de mai jos), și data la care acest document a fost actualizat.
Prezentare generală
un rezumat la nivel înalt pe care fiecare inginer din companie ar trebui să îl înțeleagă și să îl folosească pentru a decide dacă este util pentru ei să citească restul documentului., Ar trebui să fie 3 paragrafe max.o descriere a problemei la îndemână, de ce este necesar acest proiect, ce trebuie să știe oamenii pentru a evalua acest proiect și cum se încadrează în strategia tehnică, strategia produsului sau obiectivele trimestriale ale echipei.,
Obiective și Non-Obiective
Obiectivele secțiune ar trebui să:
- descrie user-driven impactul proiectului — în cazul în care utilizator ar putea fi o altă echipă de ingineri sau chiar un alt sistem tehnic
- specifica cum pentru a măsura succesul folosind metrici — puncte bonus dacă puteți link-ul de la un tablou de bord care urmărește aceste valori
Non-Obiectivele sunt la fel de importante pentru a descrie ce probleme ai de nu va fi de fixare astfel încât toată lumea este pe aceeași pagină.,
Repere
O listă de puncte de control măsurabile, astfel încât PM și manager poate degresat și știu cam când diferite părți ale proiectului va fi realizat. Vă încurajez să împărțiți proiectul în repere majore cu care se confruntă utilizatorii dacă proiectul are o durată mai mare de 1 lună.
utilizați datele din calendar pentru a lua în considerare întârzierile, vacanțele, întâlnirile și așa mai departe., Acesta ar trebui să arate ceva de genul asta:
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
Adăugați un subsecțiunea aici dacă ETA de unele dintre aceste piatră de hotar modificări, astfel încât părțile interesate să poată vedea cu ușurință cele mai up-to-data de estimări.
soluție existentă
pe lângă descrierea implementării curente, ar trebui să parcurgeți și un flux de exemplu la nivel înalt pentru a ilustra modul în care utilizatorii interacționează cu acest sistem și/sau modul în care fluxul de date prin acesta.,
o poveste de utilizator este o modalitate foarte bună de a încadra acest lucru. Rețineți că sistemul dvs. poate avea diferite tipuri de utilizatori cu diferite cazuri de utilizare.
soluție propusă
unii oameni numesc această secțiune arhitectura tehnică. Din nou, încercați să parcurgeți o poveste de utilizator pentru a concretiza acest lucru. Simțiți-vă liber pentru a include mai multe sub-secțiuni și diagrame.
furnizați mai întâi o imagine de ansamblu, apoi completați o mulțime de detalii. Scopul pentru o lume în care puteți scrie acest lucru, apoi să ia o vacanță pe o insulă pustie, și un alt inginer pe echipa poate citi doar și să pună în aplicare soluția așa cum ați descris.,
soluții Alternative
Ce altceva ați luat în considerare atunci când ați venit cu soluția de mai sus? Care sunt avantajele și dezavantajele alternativelor? V-ați gândit să cumpărați o soluție 3rd — party — sau să utilizați una open source-care rezolvă această problemă, spre deosebire de construirea propriei dvs.?Testabilitatea, monitorizarea și alertarea îmi place să includ această secțiune, deoarece oamenii tratează adesea acest lucru ca pe o gândire ulterioară sau o sar peste toate împreună și aproape întotdeauna se întoarce să-i muște mai târziu când lucrurile se sparg și nu au nici o idee cum sau de ce.,
impactul între Echipe
cum va crește această sarcină la apel și la dev-ops?
câți bani va costa?
cauzează vreo regresie a latenței în sistem?
expune vulnerabilități de securitate?
Care sunt unele consecințe negative și efecte secundare?
cum ar putea echipa de asistență să comunice acest lucru clienților?
întrebări deschise
orice probleme deschise de care nu sunteți sigur, decizii controversate pe care doriți ca cititorii să le cântărească, sugestii de lucrări viitoare și așa mai departe. Un nume de limbă în obraz pentru această secțiune este”necunoscutele cunoscute”.,
detaliate Scoping și cronologie
această secțiune este cea mai mare parte va fi citit doar de către inginerii care lucrează la acest proiect, lor Tech conduce, și managerii lor. Prin urmare, această secțiune este la sfârșitul doc.în esență ,aceasta este defalcarea modului și momentului în care intenționați să executați fiecare parte a proiectului. Există multe lucruri care intră în domeniul de aplicare cu exactitate, astfel încât să puteți citi această postare pentru a afla mai multe despre domeniul de aplicare.
am tendința de a trata, de asemenea, această secțiune a documentului de proiectare ca un tracker de activități de proiect în curs de desfășurare, așa că actualizez acest lucru ori de câte ori se schimbă estimarea mea de domeniu., Dar asta e mai mult o preferință personală.
Cum să-l scrie
Acum că am vorbit despre ce se întâmplă într-un design bun, doctore, hai sa vorbim despre stilul de scris. Promit că acest lucru este diferit de clasa ta de liceu limba engleză.
scrieți cât mai simplu
nu încercați să scrieți ca lucrările academice pe care le-ați citit. Acestea sunt scrise pentru a impresiona recenzorii jurnalului. Documentul dvs. este scris pentru a descrie soluția dvs. și pentru a obține feedback de la colegii de echipă., Puteți obține claritate prin utilizarea:
- cuvinte Simple
- fraze Scurte
- liste cu Marcatori și/sau liste numerotate
- exemple Concrete, de genul „Utilizatorul Alice se conectează contul ei, atunci …”
Adăugați o mulțime de grafice și diagrame
Diagrame pot fi adesea util pentru a compara mai multe opțiuni posibile, și diagrame sunt, în general, mai ușor de a analiza pe text. Am avut noroc cu desenul Google pentru crearea diagramelor.,sfat Pro: nu uitați să adăugați un link la versiunea editabilă a diagramei de sub captura de ecran, astfel încât să o puteți actualiza cu ușurință mai târziu, când lucrurile se schimbă inevitabil.
Include numere
scara problemei determină adesea soluția. Pentru a ajuta recenzenții să înțeleagă starea lumii, includeți numere reale precum # de rânduri DB, # de erori ale utilizatorilor — latență-și modul în care acestea se scalează cu utilizarea. Îți amintești notațiile tale mari?
încearcă să fii amuzant
O spec nu este o lucrare academică. De asemenea, oamenilor le place să citească lucruri amuzante, deci aceasta este o modalitate bună de a menține cititorul angajat., Nu exagerați acest lucru până la punctul de a vă îndepărta de ideea de bază.
Dacă tu, ca mine, au probleme in a fi amuzant, Joel Spolsky (evident, cunoscut pentru sale de comedie talente…) acest sfat:
Una dintre cele mai simple moduri de a fi amuzant este de a fi specific, atunci când nu este solicitat în Loc de a spune „interese speciale”, spun „stângaci avacado fermieri.”
Face Sceptic Test
Înainte de a trimite un design doc pentru alții să revizuiască, să treacă pe la ea pretinde a fi referent. Ce întrebări și îndoieli ați putea avea despre acest design?, Atunci adresează-le preventiv.dacă mergeți într-o vacanță lungă acum fără acces la internet, poate cineva din echipa dvs. să citească documentul și să îl implementeze așa cum ați intenționat?scopul principal al unui document de proiectare nu este schimbul de cunoștințe, dar aceasta este o modalitate bună de a evalua claritatea, astfel încât ceilalți să vă poată oferi feedback util.
Proces
Ah, da, temut P-cuvântul., Documentele de proiectare vă ajută să obțineți feedback înainte de a pierde o grămadă de timp implementând soluția greșită sau soluția problemei greșite. Există o mulțime de artă pentru a obține un feedback bun, dar asta este pentru un articol ulterior. Deocamdată, să vorbim în mod specific despre cum să scrieți documentul de proiectare și să obțineți feedback pentru acesta.în primul rând, toți cei care lucrează la proiect ar trebui să facă parte din procesul de proiectare. Este în regulă dacă conducerea tehnică ajunge să conducă o mulțime de decizii, dar toată lumea ar trebui să fie implicată în discuție și să cumpere designul., Deci, ” tu „de-a lungul acestui articol este un adevărat plural” tu ” care include toți oamenii din proiect.
În al doilea rând, procesul de proiectare nu înseamnă că te uiți la ideile de teoretizare a tablei albe. Simțiți-vă liber să vă murdăriți mâinile și să prototipați soluții potențiale. Acest lucru nu este același lucru cu a începe să scrieți codul de producție pentru proiect înainte de a scrie un document de proiectare. Nu face asta. Dar ar trebui să vă simțiți liber să scrieți un cod hacky throwaway pentru a valida o idee., Pentru a vă asigura că scrieți doar Cod exploratoriu, faceți o regulă că niciunul din acest cod prototip nu se îmbină cu master.
după aceea, pe măsură ce începeți să aveți o idee despre cum să faceți proiectul dvs., faceți următoarele:
- cereți unui inginer cu experiență sau șef tehnic din echipa dvs. să fie recenzorul dvs. În mod ideal, aceasta ar fi cineva care este bine respectat și/sau familiarizat cu cazurile de margine ale problemei. Mituiți-i cu boba, dacă este necesar.
- du-te într-o sală de conferințe cu o tablă albă.,
- descrieți problema pe care o abordați acestui inginer (acesta este un pas foarte important, nu o săriți!).
- apoi explicați implementarea pe care o aveți în minte și convingeți-i că acesta este lucrul corect de construit.făcând toate acestea înainte de a începe chiar să scrieți documentul de proiectare vă permite să obțineți feedback cât mai curând posibil, înainte de a investi mai mult timp și de a vă atașa de orice soluție specifică., Adesea, chiar dacă implementarea rămâne aceeași, examinatorul dvs. este capabil să sublinieze cazurile de colț pe care trebuie să le acoperiți, să indice orice zone potențiale de confuzie și să anticipeze dificultățile pe care le-ați putea întâmpina ulterior.
Apoi, după ce am scris o schiță de design doc, pentru a primi același referent de a citi prin ea din nou, și ștampilă de cauciuc prin adăugarea de numele lor, ca referent în Titlu și Oameni secțiunea de design doc. Acest lucru creează stimulente suplimentare și responsabilitate pentru examinator.,în această notă, luați în considerare adăugarea de revizori specializați (cum ar fi SREs și ingineri de securitate) pentru aspecte specifice ale proiectării.
după ce și referent(e) să semneze, nu ezitați să trimiteți doc design pentru echipa ta pentru feedback suplimentar și schimbul de cunoștințe. Vă sugerez să limitați acest proces de colectare a feedback-ului la aproximativ 1 săptămână pentru a evita întârzierile prelungite. Angajați-vă să abordați toate întrebările și comentariile pe care oamenii le părăsesc în acea săptămână. Lăsând comentarii agățat = karma rău.,
în cele din Urmă, dacă există o mulțime de dispută între tine, referent, și alte inginerii citirea doc, vă recomandăm cu tărie consolidarea toate punctele de dispută în secțiunea de Discuții de doc. Apoi, stabiliți o întâlnire cu diferitele părți pentru a vorbi despre aceste dezacorduri în persoană.ori de câte ori un fir de discuție are mai mult de 5 comentarii, trecerea la o discuție în persoană tinde să fie mult mai eficientă. Rețineți că sunteți în continuare responsabil pentru efectuarea apelului final, chiar dacă toată lumea nu poate ajunge la un consens.,
În a vorbi cu Shrey Banga recent despre asta, am aflat că Quip are un proces similar, cu excepția în plus, pentru a avea un inginer cu experiență sau tech duce pe echipa ta ca un referent, ele sugerează, de asemenea, având un inginer pe o altă echipă de revizuire doc. Nu am încercat acest lucru, dar cu siguranță pot vedea acest lucru ajutând la obținerea de feedback de la oameni cu perspective diferite și la îmbunătățirea lizibilității generale a documentului.după ce ați făcut toate cele de mai sus, timp pentru a merge pe punerea în aplicare!, Pentru puncte suplimentare de brownie, tratați acest document de design ca un document viu pe măsură ce implementați designul. Actualizați documentul de fiecare dată când învățați ceva care vă duce la modificarea soluției originale sau la actualizarea domeniului de aplicare. Îmi vei mulțumi mai târziu, când nu va trebui să explici lucrurile de mai multe ori tuturor părților interesate.în cele din urmă, să obținem într-adevăr meta pentru o secundă: cum evaluăm succesul unui document de design?
colegul meu Kent Rakip are un răspuns bun la acest lucru: un document de proiectare are succes dacă se face ROI-ul corect al muncii.,ts arhitecturii tehnice
- obțineți feedback de la comentatorii care
Xeste cea mai riscantă parte din arhitectura propusă - Vă decideți să pună în aplicare
Xprima de risc a proiectului - 3 zile mai târziu, îți dai seama că
Xnu este posibil, sau mult mai dificil decât ați intenționat inițial - Vă decideți pentru a opri de lucru pe acest proiect și să acorde prioritate altor lucrări în schimb
La începutul acestui articol, ne-a declarat obiectivul de un design doc este de a asigura dreptul să-și facă treaba., În exemplul de mai sus, datorită acest design doc, în loc de a pierde potențial luni doar pentru a abandona acest proiect, mai târziu, am petrecut 8 zile. Mi se pare un rezultat destul de reușit.
vă rugăm să lăsați un comentariu de mai jos, dacă aveți întrebări sau feedback-ul! Mi-ar plăcea, de asemenea, să aud despre modul în care proiectați documente diferit în echipa dvs.acordarea de credit în cazul în care creditul se datorează, am învățat o mulțime de cele de mai sus, lucrând alături de niște ingineri incredibili la Plaid (angajăm! Vino de proiectare și de a construi unele sisteme tehnice dulci cu noi) și Quora.,dacă vă place această postare, urmați-mă pe Twitter pentru mai multe postări despre inginerie, procese și sisteme backend.