av Angela Zhang
Som en programvare ingeniør, jeg bruker mye tid på lesing og skriving av design dokumenter. Etter å ha gått gjennom hundrevis av disse dokumentene, jeg har sett første hånd er en sterk sammenheng mellom god design dokumenter og den ultimate suksessen til prosjektet.
Denne artikkelen er mitt forsøk på å beskrive hva som gjør en design dokument stor.,
artikkelen er delt inn i 4 deler:
- Hvorfor skrive en design document
- Hva som skal inkluderes i en design-dokument
- Hvordan å skrive den
- prosess rundt det
Hvorfor skrive en design-dokument?
En design doc — også kjent som en teknisk spec — er en beskrivelse av hvordan du har tenkt å løse et problem.
Det er mange skrifter allerede på hvorfor det er viktig å skrive en design doc før dykking i koding. Så alt jeg vil si her er:
En design doc er den mest nyttige verktøyet for å sørge for riktig arbeidet blir gjort.,
Det viktigste målet for en design doc er å gjøre deg mer effektiv ved å tvinge deg til å tenke gjennom design og samle tilbakemeldinger fra andre. Folk tror ofte det punktet av en design doc er til å lære andre om noe system eller tjene som dokumentasjon senere. Mens de kan være gunstig bivirkninger, de er ikke målet i seg selv.
Som en generell tommelfingerregel, hvis du arbeider på et prosjekt som kan ta 1 ingeniør-måned eller mer, bør du skrive en design doc. Men det stopper ikke der — en rekke mindre prosjekter kan dra nytte av en mini design doc også.
Flott!, Hvis du fortsatt leser, du tror på betydningen av design dokumenter. Imidlertid forskjellige engineering team, og selv ingeniører innenfor det samme teamet, ofte skrive design dokumenter svært forskjellig. Så la oss snakke om innhold, stil, og prosessen med en god design doc.
Hva som skal inkluderes i en design, doc?
En design doc beskriver løsningen på et problem. Siden arten av hver problemet er forskjellige, naturligvis du ønsker å strukturere design doc annen måte.,
Til å begynne med, følgende er en liste over deler som du burde i det minste vurdere inkludert i din neste design dok:
Tittel og Mennesker
tittelen på din design doc, author(s) (bør være den samme som for liste over folk planlegger å jobbe på dette prosjektet), og redaktør(er) doc (vi skal snakke mer om det i Prosessen avsnittet nedenfor), og datoen for dette dokumentet sist ble oppdatert.
Oversikt
Et høyt nivå sammendrag som hver ingeniør hos selskapet bør forstå og bruke for å avgjøre om det er nyttig for dem å lese resten av doc., Det bør være 3 avsnitt maks.
Kontekst
En beskrivelse av problemet på hånden, hvorfor prosjektet er nødvendig, hva folk trenger å vite for å vurdere dette prosjektet, og hvordan det passer inn i den tekniske strategi, produkt-strategi, eller lagets kvartalsvis mål.,
Mål og Ikke-Mål
Målene delen skal:
- beskrive brukerstyrt effekten av prosjektet — der brukeren kan være en annen engineering team eller annen teknisk system
- angi hvordan å måle suksess ved hjelp av beregninger — bonus poeng hvis du kan lenke til en oversikt som følger med på de beregninger
Ikke-Mål er like viktig å beskrive hvilke problemer du vil ikke bli fikse slik at alle er på samme side.,
Milepæler
En liste over målbare sjekkpunkter, slik at PM og din leder er manager kan se det og vite omtrent når ulike deler av prosjektet vil bli utført. Jeg oppfordrer deg til å bryte prosjektet ned i store bruker-mot milepæler dersom prosjektet er mer enn 1 måned lang.
Bruk kalender datoer, slik at du ta hensyn til relatert forsinkelser, ferier, møter og så videre., Det skal se ut noe 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
Legge til en ledd her hvis ETA av noen av disse milepæl endringer, så interessenter kan enkelt se de mest up-to-date estimater.
Eksisterende Løsning
I tillegg til å beskrive gjeldende implementering, bør du også gå gjennom et høyt nivå eksempel flyt for å illustrere hvordan brukerne samhandler med dette systemet og/eller hvordan data flyter gjennom det.,
En bruker historien er en flott måte å tilpasse dette. Husk at systemet kan ha ulike typer av brukere med ulike bruksmåter.
Foreslått Løsning
Noen kaller dette den Tekniske Arkitekturen delen. Igjen, kan du prøve å gå gjennom en bruker historien til å concretize dette. Føl deg fri til å omfatte flere sub-seksjoner og diagrammer.
Gi et stort bilde først, og deretter fylle i mange av detaljene. Målet for en verden der du kan skrive dette, så ta en ferie på noen øde øy, og en annen ingeniør på laget kan bare lese den og implementere løsningen som du beskrev.,
Alternative Løsninger
Hva annet gjorde du bør vurdere når du kommer opp med løsningen ovenfor? Hva er fordeler og ulemper med alternativene? Har du vurdert å kjøpe en 3. part løsning — eller ved hjelp av en åpen kildekode — det løser dette problemet, i motsetning til å bygge din egen?
Testability, Overvåking og Varsling
jeg liker inkludert dette avsnittet, fordi folk ofte behandle dette som en ettertanke eller hoppe over det alle sammen, og det er nesten alltid kommer tilbake for å bite dem senere når ting pause, og de har ingen anelse om hvordan eller hvorfor.,
Cross-Team Innvirkning
Hvordan vil dette øke på samtalen og dev-ops byrde?
Hvor mye penger vil det koste?
Ikke det føre til noen ventetid regresjon til systemet?
Betyr det å utsette noen sikkerhetsproblemer?
Det er noen negative konsekvensene og bivirkninger?
Hvordan du kan støtte laget å kommunisere dette til kundene?
Åpne Spørsmål
Noen åpne spørsmål som du ikke er sikker på, kontroversielle avgjørelser som du ønsker leserne å veie inn på, foreslo videre arbeid, og så videre. En tongue-in-cheek navn for denne delen er de «kjente ukjente».,
Detaljert Omfang og Tidslinje
Denne delen er for det meste kommer til å leses bare av ingeniører som har jobbet med dette prosjektet, deres tech fører, og deres ledere. Derfor denne delen er på slutten av doc.
Egentlig, dette er oversikt over hvordan og når du planlegger å utføre hver del av prosjektet. Det er mye som går inn definisjonsområdet nøyaktig, så kan du lese dette innlegget for å lære mer om omfang.
jeg har en tendens til å også behandle denne delen av design doc som et pågående prosjekt oppgave tracker, så jeg oppdatere denne når min scoping estimat endringer., Men det er mer av en personlig preferanse.
Hvordan å skrive den
Nå som vi har snakket om hva som går inn i en god design, doc, la oss snakke om skrivestil. Jeg lover at dette er noe annet enn high school engelsk klasse.
Skriv så enkelt som mulig
ikke prøv å skrive som de akademiske artikler du har lest. De er skrevet for å imponere journal anmeldere. Doc er skrevet for å beskrive løsningen din og få tilbakemelding fra dine lagkamerater., Du kan oppnå klarhet ved å bruke:
- Enkle ord
- Korte setninger
- Punktmerkede lister og/eller nummererte lister
- Konkrete eksempler, for eksempel «User Alice kobler henne bankkonto, så …»
Legg til massevis av grafer og diagrammer
Diagrammer kan ofte være nyttig å sammenligne flere potensielle alternativer, og diagrammer er generelt lettere å analysere enn tekst. Jeg har hatt hell med Google Tegne for å lage diagrammer.,
Pro Tips: husk å legge til en link til redigerbar versjon av diagrammet under skjermen, slik at du enkelt kan oppdatere senere når ting uunngåelig forandring.
Inneholde tall
omfanget av problemet avgjør ofte løsningen. For å hjelpe anmeldere få en følelse av state of the world, inkluder reelle tall, som for eksempel # av DB rader, # av brukeren feil, ventetid — og hvordan disse skala med bruk. Husk Big-O merknader?
Prøv å være morsom
En spec er ikke en akademisk papir. Også, folk liker å lese morsomme ting, så dette er en god måte å holde leseren engasjert., Ikke overdriv dette til det punktet av å ta bort fra kjernen i ideen om.
Hvis du, som meg, har problemer med å være morsomme, Joel Spolsky (åpenbart kjent for sine komiske talenter…) har dette tipset:
En av de enkleste måtene å være morsom er å være spesifikk når det ikke kalles for i Stedet for å si «spesielt interesserte,» sier «venstre-hånds avacado bønder.»
Gjøre den Skeptiske Test
Før du sender din design doc til andre å vurdere, ta en pass på det som utgir seg for å være kontrollør. Hvilke spørsmål og tvil kan du ha om dette designet?, Deretter løse dem preemptively.
Gjøre den Ferien Test
Hvis du går på en lang ferie nå uten internett-tilgang, kan noen som er på ditt lag lese doc og gjennomføre det som du hadde tenkt?
Det viktigste målet for en design doc er ikke dele kunnskap, men dette er en god måte å evaluere for klarhet, slik at andre kan faktisk gi deg nyttig tilbakemelding.
Behandle
Ah ja, den fryktede P-ordet., Design dokumenter hjelpe deg å få tilbakemeldinger før du kaste bort en masse tid å implementere feil løsning eller løsningen på feil problem. Det er mye kunst å få gode tilbakemeldinger, men det er for en senere artikkel. For nå, la oss bare snakke spesifikt om hvordan å skrive design doc og få tilbakemeldinger på det.
Først av alt, alle som jobber på prosjektet bør være en del av designprosessen. Det er greit hvis tech føre ender opp med å kjøre mye av beslutningene, men alle bør være involvert i diskusjonen, og kjøpe seg inn i utformingen., Så det «du» i hele denne artikkelen er en virkelig flertall «du» som omfatter alle personer på prosjektet.
for det Andre, designprosessen, betyr ikke at du stirrer på tavle teoretisering ideer. Føl deg fri til å få hendene skitne og prototype potensielle løsninger. Dette er ikke det samme som å begynne å skrive produksjon koden for prosjektet før du skriver en design doc. Ikke gjør det. Men du absolutt skal føle deg fri til å skrive noen hacky bruk-og-kast-koden for å validere en idé., For å sikre at du bare skrive utforskende-koden, gjør det til en regel at ingen av denne prototypen koden blir slått sammen til master.
Etter det, når du starter å ha noen idé om hvordan du skal gå om prosjektet ditt, kan du gjøre følgende:
- Spør en erfaren ingeniør eller teknisk føre på ditt team å være anmelder. Ideelt sett ville dette være noen som er respektert og/eller kjent med kanten tilfeller av problemet. Bestikke dem med boba hvis det er nødvendig.
- Gå inn i et konferanserom med en tavle.,
- Beskrive problemet du håndterer denne ingeniør (dette er et svært viktig skritt, ikke hopp over det!).
- Da forklare gjennomføringen du har i tankene, og overbevise dem om dette er den riktige tingen å bygge.
å Gjøre alt dette selv før du begynner å skrive din design doc kan du få tilbakemelding så snart som mulig, før du investerer mer tid og få knyttet til en bestemt løsning., Ofte, selv om gjennomføringen forblir den samme, kontrolløren er i stand til å peke ut hjørne tilfeller må du dekke, tyder på alle mulige områder av forvirring, og forutse problemer du kan støte på et senere tidspunkt.
Så, etter at du har skrevet et grovt utkast til design, doc, få den samme anmelder til å lese gjennom det igjen, og stempel det ved å legge til navnet sitt som leser i Tittel og Folk-delen av design doc. Dette skaper ekstra insentiv og ansvarlighet for anmelderen.,
På dette notatet, kan du vurdere å legge til spesialisert anmeldere (for eksempel SREs og sikkerhet ingeniører) for spesifikke aspekter i design.
Når du og anmelder(s) logge deg av, føl deg fri til å sende design doc til ditt team for ytterligere tilbakemelding og deling av kunnskap. Jeg foreslår at gang-byksende denne tilbakemeldinger gathering prosessen til ca 1 uke for å unngå lengre forsinkelser. Forplikte seg til å ta opp alle spørsmål og kommentarer fra folk forlater innenfor denne uken. Å la kommentarer hengende = dårlig karma.,
til Slutt, hvis det er mye uenighet mellom deg, din anmelder, og andre ingeniører lese doc, vil jeg sterkt anbefale å konsolidere alle punkter i påstanden i Diskusjonen delen av doc. Så, sette opp et møte med de ulike partene til å snakke om disse uenighetene i person.
Når en diskusjon tråden er mer enn 5 kommentarer lang, flytte til en person diskusjonen har en tendens til å være langt mer effektiv. Husk at du er fortsatt ansvarlig for å gjøre den siste samtale, selv om alle kan ikke komme til en konsensus.,
I å snakke med Shrey Banga nylig om dette, jeg lærte at Quip har en lignende prosess, unntatt i tillegg til å ha en erfaren ingeniør eller teknisk leder på laget ditt som anmelder, de også foreslå å ha en ingeniør på et annet lag gjennomgang doc. Jeg har ikke prøvd dette, men jeg kan absolutt se dette bidrar få tilbakemeldinger fra mennesker med ulike perspektiver og forbedre den generelle lesbarheten av doc.
Når du har gjort alle de ovennevnte, tid til å få gå på gjennomføringen!, For ekstra brownie poeng, behandle dette design-doc som et levende dokument som du implementere design. Oppdatere doc hver gang du lære noe som fører til at du gjør endringer i den opprinnelige løsningen, eller oppdatere din scoping. Du vil takke meg senere når du ikke trenger å forklare tingene om og om igjen til alle interessenter.
til Slutt, la oss få virkelig meta for andre: Hvordan skal vi evaluere resultatene av en design doc?
Min kollega Kent Rakip har et godt svar på dette: En design doc er vellykket hvis høyre AVKASTNINGEN av arbeidet som er gjort.,ts av teknisk arkitektur
X er den mest risikable delen av den foreslåtte arkitekturenX første til å de-risiko prosjektetX er enten ikke er mulig, eller langt vanskeligere enn du opprinnelig hadde tenkti begynnelsen av denne artikkelen, vi sa at målet om en design doc er å sørge for at den rette jobben blir gjort., I eksempelet ovenfor, takket være dette design doc, i stedet for å kaste bort potensielt måneder bare for å avbryte dette prosjektet senere, du bare har tilbrakt 8 dager. Virker som en ganske vellykket resultat for meg.
Vennligst legg igjen en kommentar nedenfor hvis du har noen spørsmål eller tilbakemeldinger! Jeg vil også gjerne høre om hvordan du gjør design dokumenter på en annen måte i ditt team.
å Gi kreditt der kreditt skyldes, jeg lærte mye av det ovenfor ved å arbeide sammen med noen utrolige ingeniører ved Rutete (vi leier! Kommer designe og bygge noen søte tekniske systemer med oss) og Quora.,
Hvis du liker dette innlegget, kan du følge meg på Twitter for flere innlegg på engineering, prosesser og bakenforliggende systemer.