Sådan skriver du et godt software design doc

Som softwareingeniør bruger jeg meget tid på at læse og skrive designdokumenter. Efter at have gennemgået hundredvis af disse dokumenter, har jeg fra første hånd set en stærk sammenhæng mellem gode designdokumenter og den ultimative succes for 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 et designdokument
  • Hvad skal man medtage i et designdokument
  • Hvordan man skriver det
  • Den proces omkring det

Hvorfor skrive et designdokument?

Et designdokument - også kendt som en teknisk specifikation - 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 ned i kodning. Så alt hvad jeg vil sige her er:

Et designdokument er det mest nyttige værktøj til at sikre, at det rigtige arbejde bliver gjort.

Hovedmålet med et designdokument er at gøre dig mere effektiv ved at tvinge dig til at tænke igennem designet og samle feedback fra andre. Folk tror ofte, at pointen med et designdokument er at lære andre om et system eller tjene som dokumentation senere. Selvom disse kan være gavnlige bivirkninger, er de ikke målet i sig selv.

Hvis du arbejder på et projekt, der kan tage en ingeniørmåned eller mere, skal du som hovedregel skrive et designdokument. Men stop ikke der - mange mindre projekter kan også drage fordel af et mini design doc.

Store! Hvis du stadig læser, tror du på vigtigheden af ​​designdokumenter. Imidlertid skriver forskellige ingeniørteam og endda ingeniører inden for det samme team ofte designdokumenter meget forskelligt. Så lad os tale om indholdet, stilen og processen med et godt designdokument.

Hvad skal jeg medtage i et designdokument?

Et designdokument beskriver løsningen på et problem. Da hvert problem er forskelligt, vil du naturligvis gerne strukturere dit designdokument forskelligt.

For at starte er det følgende en liste over sektioner, som du i det mindste bør overvejeinklusive i dit næste designdokument:

Titel og mennesker

Titlen på dit designdokument, denforfatter (e) (skal være den samme som listen over personer, der planlægger at arbejde på dette projekt), korrekturlæseren (e)af dokumentet (vi taler mere om det i afsnittet Process nedenfor) og datoen for, at dette dokument sidst blev opdateret.

Oversigt

Et resumé på højt niveau, som enhver ingeniør i virksomheden skal forstå og bruge til at afgøre, om det er nyttigt for dem at læse resten af ​​dokumentet. Det skal maksimalt være 3 afsnit.

Sammenhæng

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

Målsektionen skal:

  • beskrive den brugerdrevne indvirkning af dit projekt - hvor din bruger kan være et andet ingeniørteam eller endda et andet teknisk system
  • angiv, hvordan du måler succes ved hjælp af metrics - bonuspoint, hvis du kan linke til et dashboard, der sporer disse metrics

Ikke-mål er lige så vigtige for at beskrive, hvilke problemer du ikke løser, så alle er på samme side.

Milepæle

En liste over målbare kontrolpunkter, så din PM og din chefs manager kan skimme den og vide omtrent, hvornår forskellige dele af projektet skal udføres. Jeg opfordrer dig til at opdele projektet i store milepæle, som brugeren vender, 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 skal se sådan ud:

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

Tilføj et [Update]underafsnit her, hvis ETA for nogle af disse milepæle ændres, så interessenterne let kan se de mest opdaterede skøn.

Eksisterende løsning

Ud over at beskrive den aktuelle implementering skal du også gennemgå et eksempel på et højt niveau for at illustrere, hvordan brugerne interagerer med dette system og / eller hvordan data strømmer gennem det.

En brugerhistorieer en fantastisk måde at ramme dette på. Husk, at dit system muligvis har forskellige typer brugere med forskellige brugssager.

Foreslået løsning

Nogle kalder dette sektionen 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 først et stort billede, og udfyld derefter partierafdetaljer. Mål for en verden, hvor du kan skrive dette, tag derefter en ferie på en øde ø, og en anden ingeniør på holdet kan bare læse den og implementere løsningen som du beskrev.

Alternative løsninger

Hvad mere overvejede du, når du kom på løsningen ovenfor? Hvad er fordelene og ulemperne ved alternativerne? Har du overvejet at købe en tredjepartsløsning - eller bruge 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 at inkludere dette afsnit, fordi folk ofte behandler dette som en eftertanke eller springer det hele sammen, og det kommer næsten altid tilbage for at bide dem senere, når tingene går i stykker, og de har ingen idé om, hvordan eller hvorfor.

Cross-Team Impact

Hvordan vil dette øge byrden for opkald og dev-ops?

Hvor mange penge vil det koste?

Forårsager det nogen ventetid regression til systemet?

Afslører det sikkerhedssårbarheder?

Hvad er nogle negative konsekvenser og bivirkninger?

Hvordan kan supportteamet kommunikere dette til kunderne?

Åbn spørgsmål

Eventuelle åbne spørgsmål, som du ikke er sikker på, omstridte beslutninger, som du vil have læsere til at afveje, foreslået fremtidigt arbejde osv. Et tunge-i-kind navn for dette afsnit er de "kendte ukendte".

Detaljeret Scoping og tidslinje

Dette afsnit læses for det meste kun af ingeniører, der arbejder på dette projekt, deres tekniske kundeemner og deres ledere. Derfor er dette afsnit i slutningen af ​​dokumentet.

I det væsentlige er dette en opdeling af, hvordan og hvornår du planlægger at udføre hver del af projektet. Der er meget, der går i scoping nøjagtigt, 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 designdokumentet som en løbende projektopgavetracker, så jeg opdaterer dette, når mit scopingestimat ændres. Men det er mere en personlig præference.

Hvordan man skriver det

Nu hvor vi har talt om, hvad der ligger i et godt designdokument, lad os tale om skrivestilen. Jeg lover, at dette er anderledes end din engelskkurs i gymnasiet.

Skriv så simpelt som muligt

Forsøg ikke at skrive som de akademiske papirer, du har læst. De er skrevet for at imponere journalanmeldere. Dit dokument er skrevet til at beskrive din løsning og få feedback fra dine holdkammerater. Du kan opnå klarhed ved at bruge:

  • Enkle ord
  • Korte sætninger
  • Punktlister og / eller nummererede lister
  • Konkrete eksempler, som "Bruger Alice forbinder sin bankkonto, så ..."

Tilføj masser af diagrammer og diagrammer

Diagrammer kan ofte være nyttige til at sammenligne flere mulige muligheder, og diagrammer er generelt lettere at analysere end tekst. Jeg har haft held og lykke med Google Drawing til 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 ting uundgåeligt ændres.

Inkluder tal

Problemets omfang bestemmer ofte løsningen. For at hjælpe korrekturlæsere med at få en fornemmelse af verdens tilstand skal du inkludere reelle tal som antal DB-rækker, antal brugerfejl, ventetid - og hvordan disse skaleres med brugen. Husker du dine Big-O notationer?

Prøv at være sjov

En spec er ikke en akademisk artikel. Folk kan også lide at læse sjove ting, så dette er en god måde at holde læseren engageret på. Overdriv ikke dette til det punkt at tage væk fra kerneideen.

Hvis du, ligesom mig, har problemer med at være sjov, har Joel Spolsky ( åbenbart kendt for sine komiske talenter ...) dette tip:

En af de nemmeste måder at være sjov på er at være specifik, når det ikke kræves [... Eksempel:] I stedet for at sige "særlige interesser" skal du sige "venstrehåndede avacadobønder."

Udfør den skeptiske test

Inden du sender dit designdokument til andre til gennemgang, skal du tage et kig på det, foregive at være korrekturlæseren. Hvilke spørgsmål og tvivl kan du have om dette design? Derefter adresser dem forebyggende.

Lav ferietesten

Hvis du tager på en lang ferie nu uden internetadgang, kan nogen på dit team læse dokumentet og implementere det som du havde tænkt dig?

Hovedmålet med et designdokument er ikke videndeling, men dette er en god måde at evaluere for klarhed, så andre faktisk kan give dig nyttig feedback.

Behandle

Ah ja, det frygtede P-ord . Designdokumenter hjælper dig med at få feedback, inden 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. Lad os lige nu tale specifikt om, hvordan man skriver designdokumentet og får feedback til det.

Først og fremmest skal alle, der arbejder på projektet, være en del af designprocessen. Det er okay, hvis den tekniske føring ender med at køre mange af beslutningerne, men alle skal være involveret i diskussionen og købe ind i designet. Så "dig" i hele denne artikel er et rigtigt flertal "dig", der inkluderer alle mennesker på projektet.

For det andet betyder designprocessen ikke, at du stirrer på whiteboard-teoretiserende ideer. Du er velkommen til at gøre 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. Gør ikke det. Men du burde absolut være fri til at skrive en hacky smidkode for at validere en idé. For at sikre, at du kun skriver sonderende kode, skal du gøre det til en regel, at ingen af ​​denne prototypekode bliver flettet til master .

Derefter skal du gøre følgende, når du begynder at få en idé om, hvordan du går videre med dit projekt:

  1. Bed en erfaren ingeniør eller teknisk leder på dit team om at være din anmelder. Ideelt set ville dette være en person, der er respekteret og / eller fortrolig med kanten af ​​problemet. Bestik dem med boba, hvis det er nødvendigt.
  2. Gå ind i et konferencelokale med en tavle.
  3. Beskriv det problem , du tackler for denne ingeniør (dette er et meget vigtigt skridt, spring det ikke over!).
  4. 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, inden du overhovedet begynder at skrive dit designdokument, kan du få feedback hurtigst muligt, inden du investerer mere tid og bliver knyttet til en bestemt løsning. Selvom implementeringen forbliver den samme, er din anmelder ofte i stand til at påpege hjørnesager, du skal dække, angive eventuelle forvirringsområder og forudse vanskeligheder, du kan støde på senere.

Derefter, efter at du har skrevet et groft kladde af dit designdokument, skal du få den samme anmelder til at læse igennem det igen, og gummimærke det ved at tilføje deres navn som korrekturlæseren i afsnittet Titel og personer i designdokumentet. Dette skaber yderligere incitament og ansvarlighed for korrekturlæseren.

På den note, overvej at tilføje specialiserede korrekturlæsere (såsom SRE'er og sikkerhedsingeniører) til specifikke aspekter af designet.

Når du og korrekturlæseren logger af, er du velkommen til at sende designdokumentet til dit team for yderligere feedback og videndeling. Jeg foreslår, at denne feedbackindsamlingsproces tidsbegrænses til ca. 1 uge for at undgå langvarige forsinkelser. Forpligt dig til at adressere alle spørgsmål og kommentarer, som folk efterlader inden for den uge. Efterlader kommentarer hængende = dårlig karma.

Endelig, hvis der er meget uenighed mellem dig, din korrekturlæser og andre ingeniører, der læser dokumentet, anbefaler jeg stærkt at konsolidere alle stridspunktene i diskussionsafsnittet i dit dok. Lav derefter et møde med de forskellige parter for at tale personligt om disse uenigheder.

Når en diskussionstråd er mere end 5 kommentarer lang, har det en tendens til at være mere effektiv 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.

Da jeg for nylig talte med Shrey Banga om dette, lærte jeg, at Quip har en lignende proces, bortset fra at have en erfaren ingeniør eller teknisk leder på dit team som en korrekturlæser, de foreslår også at have en ingeniør på et andet hold, der gennemgår doktoren. Jeg har ikke prøvet dette, men jeg kan bestemt se, at dette hjælper med at få feedback fra mennesker med forskellige perspektiver og forbedre dokuments generelle læsbarhed.

Når du har gjort alt ovenstående, er det tid til at komme i gang med implementeringen! For ekstra brownie-punkter 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 opdaterer din scoping. Du vil takke mig senere, når du ikke behøver at forklare ting igen og igen for alle dine interessenter.

Endelig, lad os virkelig få meta et øjeblik: Hvordan vurderer vi succesen med et designdokument?

Min kollega Kent Rakip har et godt svar på dette: Et designdokument er vellykket, hvis det rigtige investeringsafkast er gjort. Det betyder, at et vellykket designdokument faktisk kan føre til et resultat som dette:

  1. Du bruger 5 dage på at skrive designdokumentet, hvilket tvinger dig til at tænke igennem forskellige dele af den tekniske arkitektur
  2. Du får feedback fra korrekturlæsere, der Xer den mest risikable del af den foreslåede arkitektur
  3. Du beslutter dig for Xførst at implementere for at risikere projektet
  4. 3 dage senere finder du ud af, at Xdet enten ikke er muligt eller langt sværere end du oprindeligt havde tænkt dig
  5. Du beslutter at stoppe med at arbejde på dette projekt og prioritere andet arbejde i stedet

I begyndelsen af ​​denne artikel sagde vi, at målet med et designdokument er at sikre, at det rigtige arbejde bliver udført. I eksemplet ovenfor har du kun brugt 8 dage takket være dette designdokument i stedet for at spilde potentielt måneder kun for at afbryde dette projekt senere. Virker som et ret succesfuldt 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 docs forskelligt i dit team.

Ved 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 Quora.

Hvis du kan lide dette indlæg, skal du følge mig på Twitter for flere indlæg om teknik, processer og backend-systemer.