af Angela Zhang
Som en software ingeniør, jeg bruger en masse tid på at læse og skrive design dokumenter. Efter at have været igennem hundredvis af disse dokumenter, har jeg set første hånd en stærk sammenhæng mellem gode design docs og den ultimative succes af projektet.
Denne artikel er mit forsøg på at beskrive, hvad der gør et designdokument godt.,
artiklen er opdelt i 4 sektioner:
- Hvorfor skrive en design dokument
- Hvad der skal indgå i en design dokument
- Hvordan til at skrive det
- processen omkring det
Hvorfor skrive en design dokument?
et design doc — også kendt som en teknisk spec — er en beskrivelse af, hvordan du planlægger at løse et problem.
Der er allerede mange skrifter om, hvorfor det er vigtigt at skrive et designdokument, før du dykker ind i kodning. Så alt jeg vil sige her er:
et design doc er det mest nyttige værktøj til at sikre, at det rigtige arbejde bliver gjort.,
hovedformålet med et design doc er at gøre dig mere effektiv ved at tvinge dig til at tænke gennem designet og samle feedback fra andre. Folk tror ofte, at pointen med et design doc er at lære andre om et system eller tjene som dokumentation senere. Mens disse kan være gavnlige bivirkninger, de er ikke målet i sig selv.
som en generel tommelfingerregel, Hvis du arbejder på et projekt, der kan tage 1 ingeniørmåned eller mere, skal du skrive et designdokument. Men stop ikke der — mange mindre projekter kunne også drage fordel af et mini design doc.
fantastisk!, Hvis du stadig læser, tror du på vigtigheden af design docs. Imidlertid skriver forskellige ingeniørhold og endda ingeniører inden for det samme team ofte design docs meget forskelligt. Så lad os tale om indholdet, stilen og processen med et godt design doc.
Hvad der skal indgå i et design, doc?
et design doc beskriver løsningen på et problem. Da arten af hvert problem er anderledes, vil du naturligvis strukturere dit design doc forskelligt.,
for At starte, følgende er en liste af afdelinger som du bør i det mindste overveje at medtage i din næste design-dokument:
Titel og Mennesker
afsnit af dit design, doc, forfatter(e) (bør være den samme som listen af folk, der planlægger at arbejde på dette projekt), reviewer(r) doc (vi vil tale mere om, at der i Processen afsnit nedenfor), og den dato, hvor dette dokument blev sidst opdateret.
oversigt
et resum.på højt niveau, som enhver ingeniør i virksomheden skal forstå og bruge til at beslutte, om det er nyttigt for dem at læse resten af dokumentet., Det skal være 3 afsnit maks.
kontekst
en beskrivelse af det aktuelle problem, hvorfor dette projekt er nødvendigt, hvad folk har brug for at vide for at vurdere dette projekt, og hvordan det passer ind i den tekniske strategi, produktstrategi eller holdets kvartalsmål.,
Mål og Ikke-Mål
De Mål, sektion:
- beskrive user-driven effekt af projektet — hvor din bruger, kan være en anden ingeniør team eller endda en anden teknisk system
- angiv, hvordan man måler succes med at anvende målinger — bonus point, hvis du kan linke til et dashboard, der sporer dem målinger
Ikke-Mål, som er lige så vigtigt at beskrive, hvilke problemer, du vil ikke blive fastsættelse, så alle er på samme side.,
milepæle
en liste over målbare kontrolpunkter, så din PM og din leders manager kan skumme det og vide groft, hvornår forskellige dele af projektet vil blive udført. Jeg opfordrer dig til at bryde projektet ned i større brugervendte milepæle, hvis projektet er mere end 1 måned langt.
brug kalenderdatoer, så du tager højde for ikke-relaterede forsinkelser, ferier, møder og så videre., Det bør se noget som dette:
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
Tilføje en underafdeling her hvis ETA af nogle af disse milepæl ændringer, så interessenterne let kan se de mest up-to-date skøn.
eksisterende løsning
ud over at beskrive den aktuelle implementering skal du også gå gennem et eksempel på højt niveau for at illustrere, hvordan brugere interagerer med dette system, og / eller hvordan data strømmer gennem det.,
en brugerhistorie er en fantastisk måde at indramme dette på. Husk, at dit system kan have forskellige typer af brugere med forskellige use cases.
foreslået løsning
Nogle mennesker kalder dette afsnittet teknisk arkitektur. Prøv igen at gå gennem en brugerhistorie for at konkretisere dette. Du er velkommen til at medtage mange underafsnit og diagrammer.
Giv et stort billede først, og udfyld derefter masser af detaljer. Sigt efter en verden, hvor du kan skrive dette, så tag en ferie på en øde ø, og en anden ingeniør på teamet kan bare læse den og implementere løsningen som du beskrev.,
Alternative løsninger
hvad overvejede du ellers, da du kom med løsningen ovenfor? Hvad er fordele og ulemper ved alternativerne? Har du overvejet at købe en 3. — parts løsning — eller ved hjælp af en open source-der løser dette problem i modsætning til at bygge din egen?
Testbarhed, Overvågning og Alarmering
jeg kan godt lide, herunder dette afsnit, fordi folk ofte behandle dette som en eftertanke, eller springe det alle sammen, og det er næsten altid kommer tilbage til at bide dem senere, når ting pause, og de har ingen idé om, hvordan eller hvorfor.,
Cross-Team Impact
hvordan vil denne stigning på opkald og dev-ops byrde?
Hvor mange penge vil det koste?
forårsager det nogen latensregression til systemet?
er det udsætte nogen sikkerhedshuller?
Hvad er nogle negative konsekvenser og bivirkninger?
Hvordan kan supportteamet kommunikere dette til kunderne?
åbne spørgsmål
eventuelle åbne problemer, som du ikke er sikker på, omstridte beslutninger, som du gerne vil have læsere til at overveje, foreslået fremtidigt arbejde osv. Et tunge-i-kind navn til dette afsnit er “kendte ukendte”.,
detaljeret Scoping og tidslinje
dette afsnit læses for det meste kun af ingeniører, der arbejder med dette projekt, deres tech leads og deres ledere. Derfor er dette afsnit i slutningen af dokumentet.
i det væsentlige er dette opdelingen af, hvordan og hvornår du planlægger at udføre hver del af projektet. Der er en masse, der går ind i scoping præcist, så du kan læse dette indlæg for at lære mere om scoping.
Jeg har en tendens til også at behandle dette afsnit af design doc som en løbende projektopgavesporing, så jeg opdaterer dette, når mit scoping-estimat ændres., Men det er mere en personlig præference.
Hvordan til at skrive det
Nu, vi har talt om, hvad der går til et godt design doc, lad os tale om den skrivestil. Jeg lover det er anderledes end din high school engelsk klasse.
skriv så enkelt som muligt
forsøg ikke at skrive som de akademiske papirer, du har læst. De er skrevet for at imponere tidsskriftsrevisorer. Dit dokument er skrevet for at beskrive din løsning og få feedback fra dine holdkammerater., Du kan opnå klarhed ved at bruge:
- Enkle ord
- Korte sætninger
- Punktopstillinger og/eller nummererede lister
- Konkrete eksempler, som “Bruger Alice forbinder hendes bankkonto, så …”
Tilføj masser af kort og diagrammer
Diagrammer kan ofte være nyttigt at sammenligne flere potentielle muligheder, og diagrammer er generelt lettere at fortolke end tekst. Jeg har haft held og lykke med Google tegning for at skabe diagrammer.,pro Tip: Husk at tilføje et link til den redigerbare version af diagrammet under skærmbilledet, så du nemt kan opdatere det senere, når tingene uundgåeligt ændres.
Medtag tal
omfanget af problemet bestemmer ofte løsningen. For at hjælpe korrekturlæsere med at få en fornemmelse af verdens tilstand skal du inkludere reelle tal som # Af DB — rækker, # af brugerfejl, latenstid-og hvordan disse skaleres med brug. Kan du huske dine store notater?
prøv at være sjovt
en spec er ikke et akademisk papir. Også folk kan lide at læse sjove ting, så det er en god måde at holde læseren engageret på., Må ikke overdrive dette til det punkt at tage væk fra kernen id.selv.
Hvis du, ligesom mig, har problemer med at være sjov, Joel Spolsky (naturligvis kendt for sine komiske talenter…) har dette tip:
En af de nemmeste måder at være sjovt, er at være specifik, når det ikke kaldes, for i Stedet for at sige “særlige interesser”, siger, at “venstre-hånds avacado landmænd.”
foretag den skeptiske Test
før du sender dit designdokument til andre for at gennemgå, skal du tage et pas på det, som om du er korrekturlæser. Hvilke spørgsmål og tvivl kan du have om dette design?, Derefter adressere dem preemptively.
Udfør Ferietesten
Hvis du går på en lang ferie nu uden internetadgang, kan nogen på dit team læse dokumentet og implementere det, som du havde til hensigt?
hovedformålet med et design doc er ikke videndeling, men det er en god måde at evaluere for klarhed, så andre rent faktisk kan give dig nyttig feedback.
Proces
Åh ja, den frygtede P-ord., Design docs hjælper dig med at få feedback, før du spilder en masse tid på at implementere den forkerte løsning eller løsningen på det forkerte problem. Der er meget kunst til at få god feedback, men det er til en senere artikel. For nu, lad os bare tale specifikt om, hvordan man skriver design doc og få feedback til det.
først og fremmest bør alle, der arbejder på projektet, være en del af designprocessen. Det er okay, hvis tech lead ender med at køre mange af beslutningerne, men alle skal være involveret i diskussionen og købe ind i designet., Så” du “i hele denne artikel er en virkelig flertal “dig”, der inkluderer alle mennesker på projektet.
for det andet betyder designprocessen ikke, at du stirrer på whithiteboardteoretiserende ideer. Du er velkommen til at få dine hænder beskidte og prototype potentielle løsninger. Dette er ikke det samme som at begynde at skrive produktionskode til projektet, før du skriver et designdokument. Lad være med det. Men du bør absolut velkommen til at skrive nogle hacky thro .a .ay kode for at validere en ID.., For at sikre, at du kun skriver sonderende kode, gør det til en regel, at ingen af denne prototype kode bliver fusioneret til master.
derefter, når du begynder at have en ID.om, hvordan du går i gang med dit projekt, skal du gøre følgende:
- Spørg en erfaren ingeniør eller teknisk leder på dit team for at være din korrekturlæser. Ideelt set ville det være en person, der er godt respekteret og / eller bekendt med kanten tilfælde af problemet. Bestikke dem med boba om nødvendigt.
- gå ind i et konferencerum med en tavle.,
- Beskriv det problem, du tackle til denne ingeniør (dette er et meget vigtigt skridt, ikke springe det!).
- forklar derefter den implementering, du har i tankerne, og overbevis dem om, at dette er den rigtige ting at bygge.
Hvis du gør alt dette, før du selv begynder at skrive dit design doc, kan du få feedback så hurtigt som muligt, før du investerer mere tid og bliver knyttet til en bestemt løsning., Selvom implementeringen forbliver den samme, er din korrekturlæser ofte i stand til at påpege hjørnesager, du har brug for at dække, angive eventuelle forvirringsområder og forudse vanskeligheder, du måtte støde på senere.
derefter, efter at du har skrevet et groft udkast til dit design doc, få den samme korrekturlæser til at læse igennem det igen, og gummistempel det ved at tilføje deres navn som korrekturlæser i afsnittet titel og personer i design doc. Dette skaber yderligere incitament og ansvarlighed for korrekturlæseren.,
overvej at tilføje specialiserede korrekturlæsere (såsom SREs og sikkerhedsingeniører) til specifikke aspekter af designet.
når du og anmelderne logger af, er du velkommen til at sende design doc til dit team for yderligere feedback og videndeling. Jeg foreslår, at denne feedbackindsamlingsproces begrænses til cirka 1 uge for at undgå udvidede forsinkelser. Forpligte sig til at løse alle spørgsmål og kommentarer folk forlader inden for denne uge. Forlader kommentarer hængende = dårlig karma.,
endelig, hvis der er meget strid mellem dig, din korrekturlæser og andre ingeniører, der læser dokumentet, anbefaler jeg stærkt at konsolidere alle stridspunkter i Diskussionsafsnittet i dit dok. Derefter oprette et møde med de forskellige parter for at tale om disse uoverensstemmelser personligt.
Når en diskussionstråd er mere end 5 kommentarer lang, har det en tendens til at være langt mere effektivt at flytte til en personlig diskussion. Husk, at du stadig er ansvarlig for at foretage det endelige opkald, selvom alle ikke kan nå til enighed.,
I taler til Shrey Banga for nylig om dette, jeg lærte, at Quip har en lignende proces, bortset fra, ud over at have en erfaren ingeniør eller teknisk leder på dit hold, som en anmelder, de foreslår også at have en ingeniør på et andet hold gennemgang doc. Jeg har ikke prøvet dette, men jeg kan helt sikkert se dette hjælpe med at få feedback fra mennesker med forskellige perspektiver og forbedre dokumentets generelle læsbarhed.
Når du har gjort alt ovenstående, tid til at komme i gang med implementeringen!, For ekstra bro .nie-Point skal du behandle dette designdokument som et levende dokument, når du implementerer designet. Opdater dokumentet, hver gang du lærer noget, der fører til, at du foretager ændringer i den originale løsning, eller opdater din scoping. Du vil takke mig senere, når du ikke behøver at forklare tingene igen og igen til alle dine interessenter.
endelig, lad os få virkelig meta for et sekund: hvordan vurderer vi succesen med et design doc?
min kollega Kent Rakip har et godt svar på dette: et design doc er vellykket, hvis det rigtige ROI af arbejdet er udført.,ts af den tekniske opbygning
X er den mest risikable del af den foreslåede opbygningX første til at de-risiko projektX enten ikke er muligt, eller langt mere vanskelig end oprindeligt tiltænkti begyndelsen af denne artikel, vi sagde, at målet med et design dokument er at sørge for at de rette arbejde bliver gjort., I eksemplet ovenfor, takket være dette design doc, i stedet for at spilde potentielt måneder kun for at afbryde dette projekt senere, har du kun brugt 8 dage. Virker som et ret vellykket resultat for mig.Efterlad en kommentar nedenfor, hvis du har spørgsmål eller feedback! Jeg vil også gerne høre om, hvordan du designer dokumenter anderledes i dit team.at give kredit, hvor kredit skyldes, lærte jeg meget af ovenstående ved at arbejde sammen med nogle utrolige ingeniører hos Plaid (vi ansætter! Kom design og bygg nogle søde tekniske systemer med os) og anduora.,
Hvis du kan lide dette indlæg, følg mig på T .itter for flere indlæg om teknik, processer og backend-systemer.