av Angela Zhang
som mjukvaruingenjör spenderar jag mycket tid på att läsa och skriva designdokument. Efter att ha gått igenom hundratals av dessa dokument, jag har sett första hand en stark korrelation mellan bra design docs och den ultimata framgången för projektet.
den här artikeln är mitt försök att beskriva vad som gör ett designdokument bra.,
artikeln är uppdelad i 4 sektioner:
- Varför skriva ett designdokument
- vad ska man inkludera i ett designdokument
- hur man skriver det
- processen runt det
varför skriva ett designdokument?
en design doc — även känd som en teknisk spec — är en beskrivning av hur du planerar att lösa ett problem.
det finns massor av skrifter redan på varför det är viktigt att skriva en design doc innan dykning i kodning. Så allt jag säger här är:
en design doc är det mest användbara verktyget för att se till att rätt arbete blir gjort.,
huvudmålet med en design doc är att göra dig mer effektiv genom att tvinga dig att tänka igenom designen och samla feedback från andra. Människor tror ofta att poängen med en design doc är att lära andra om något system eller tjäna som dokumentation senare. Även om de kan vara fördelaktiga biverkningar, är de inte målet i och för sig själva.
som en allmän tumregel, Om du arbetar med ett projekt som kan ta 1 ingenjör-månad eller mer, bör du skriva en design doc. Men sluta inte där-många mindre projekt kan också dra nytta av en mini design doc.
bra!, Om du fortfarande läser tror du på vikten av designdocs. Men olika tekniska team, och till och med ingenjörer inom samma lag, skriver ofta designdocs väldigt annorlunda. Så låt oss prata om innehållet, stilen och processen med en bra design doc.
vad ska man inkludera i en design doc?
En design doc beskriver lösningen på ett problem. Eftersom arten av varje problem är annorlunda, vill du naturligtvis strukturera din design doc annorlunda.,
för att starta är följande en lista över avsnitt som du åtminstone bör överväga att inkludera i din nästa design doc:
titel och personer
titeln på din design doc, författaren (s) (ska vara densamma som listan över personer som planerar att arbeta med detta projekt), granskaren (s) av doc (vi pratar mer om det i Processektionen nedan) och datumet då detta dokument senast uppdaterades.
översikt
en hög nivå sammanfattning som varje ingenjör på företaget bör förstå och använda för att avgöra om det är användbart för dem att läsa resten av doc., Det ska vara 3 stycken max.
sammanhang
en beskrivning av det aktuella problemet, varför det här projektet är nödvändigt, vad folk behöver veta för att bedöma detta projekt och hur det passar in i den tekniska strategin, produktstrategin eller teamets kvartalsvisa mål.,
mål och icke-mål
avsnittet mål bör:
- beskriv den användardrivna effekten av ditt projekt – där din användare kan vara ett annat ingenjörsteam eller till och med ett annat tekniskt system
- ange hur man mäter framgång med hjälp av mätvärden — bonuspoäng om du kan länka till en instrumentpanel som spårar dessa mätvärden
Icke-mål är lika viktiga för att beskriva vilka problem du inte kommer att fixa så att alla är på samma sida.,
milstolpar
en lista över mätbara kontrollpunkter, så din PM och din chef manager kan skumma det och vet ungefär när olika delar av projektet kommer att göras. Jag uppmuntrar dig att bryta ner projektet i stora användarvänliga milstolpar om projektet är mer än 1 månad lång.
använd kalenderdatum så att du tar hänsyn till orelaterade förseningar, semester, möten och så vidare., Det ska se ut så här:
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
Lägg till en underavsnitt här om ETA av några av dessa milstolpar ändras, så att intressenterna lätt kan se de mest aktuella uppskattningarna.
befintlig lösning
förutom att beskriva den aktuella implementeringen bör du också gå igenom ett exempelflöde på hög nivå för att illustrera hur användare interagerar med detta system och/eller hur data flyter genom det.,
en användarhistoria är ett bra sätt att rama in det här. Tänk på att ditt system kan ha olika typer av användare med olika användningsfall.
föreslagen lösning
vissa kallar detta avsnittet Teknisk arkitektur. Återigen, försök att gå igenom en användarhistoria för att konkretisera detta. Känn dig fri att inkludera många underavsnitt och diagram.
ge en stor bild först och fyll sedan i massor av detaljer. Sikta på en värld där du kan skriva detta, sedan ta en semester på någon öde ö, och en annan ingenjör i laget kan bara läsa den och genomföra lösningen som du beskrev.,
alternativa lösningar
vad tänkte du mer på när du kom fram till lösningen ovan? Vilka är fördelarna och nackdelarna med alternativen? Har du funderat på att köpa en 3: e parts lösning — eller använda en öppen källkod-som löser detta problem i motsats till att bygga din egen?
Testabilitet, övervakning och varning
Jag gillar att inkludera det här avsnittet, eftersom människor ofta behandlar detta som en eftertanke eller hoppa över allt tillsammans, och det kommer nästan alltid tillbaka för att bita dem senare när saker går sönder och de har ingen aning om hur eller varför.,
Cross-Team Impact
hur kommer denna ökning på call och dev-ops börda?
hur mycket pengar kommer det att kosta?
orsakar det någon latensregression till systemet ?
exponerar det några säkerhetsproblem?
vad är några negativa konsekvenser och biverkningar ?
Hur kan supportteamet kommunicera detta till kunderna?
öppna frågor
eventuella öppna problem som du inte är säker på, omtvistade beslut som du vill att läsarna ska väga in, föreslog framtida arbete och så vidare. Ett tung-i-kind namn för detta avsnitt är ”kända okända”.,
detaljerad Scoping och tidslinje
det här avsnittet kommer oftast bara att läsas av ingenjörerna som arbetar med detta projekt, deras tekniska leads och deras chefer. Därför är detta avsnitt i slutet av doc.
i huvudsak är detta fördelningen av hur och när du planerar att utföra varje del av projektet. Det finns mycket som går in i scoping exakt, så du kan läsa det här inlägget för att lära dig mer om scoping.
Jag tenderar också att behandla den här delen av design doc som en pågående projektuppgiftsspårare, så jag uppdaterar detta när min scoping-uppskattning ändras., Men det är mer av en personlig preferens.
hur man skriver det
nu när vi har pratat om vad som går in i en bra design doc, låt oss prata om skrivstilen. Jag lovar att detta är annorlunda än din high school engelska klass.
skriv så enkelt som möjligt
försök inte skriva som de akademiska papper du har läst. De är skrivna för att imponera på tidskriftsgranskare. Din doc är skriven för att beskriva din lösning och få feedback från dina lagkamrater., Du kan uppnå klarhet genom att använda:
- enkla ord
- korta meningar
- punktlistor och/eller numrerade listor
- konkreta exempel, som ”användare Alice ansluter sitt bankkonto, sedan …”
Lägg till massor av diagram och diagram
diagram kan ofta vara användbara för att jämföra flera möjliga alternativ, och diagram är i allmänhet lättare att tolka än text. Jag har haft lycka till med Google ritning för att skapa diagram.,
Pro Tips: kom ihåg att lägga till en länk till den redigerbara versionen av diagrammet under skärmdumpen, så att du enkelt kan uppdatera den senare när saker oundvikligen förändras.
inkludera nummer
problemets omfattning bestämmer ofta lösningen. För att hjälpa granskare få en känsla av tillståndet i världen, inkludera reella tal som # av DB rader, # av användarfel, latens — och hur dessa skala med användning. Kommer du ihåg dina stora noteringar?
försök att vara rolig
en spec är inte en akademisk papper. Folk gillar också att läsa roliga saker, så det här är ett bra sätt att hålla läsaren engagerad., Överdriv inte detta till den punkt att ta bort från kärntanken dock.
Om du, som jag, har problem med att vara rolig, har Joel Spolsky (uppenbarligen känd för sina komiska talanger…) detta tips:
ett av de enklaste sätten att vara rolig är att vara specifik när den inte kallas för istället för att säga” speciella intressen”, säger ” vänsterhänta Avacado bönder.”
gör skeptiska testet
innan du skickar din design doc till andra att granska, ta ett pass på det låtsas vara granskaren. Vilka frågor och tvivel kan du ha om denna design?, Ta sedan itu med dem förebyggande.
gör Semestertestet
om du går på en lång semester nu utan tillgång till internet, kan någon i ditt team läsa doc och genomföra det som du tänkt?
huvudmålet med en design doc är inte kunskapsdelning, men det här är ett bra sätt att utvärdera för tydlighet så att andra faktiskt kan ge dig användbar feedback.
Process
Ah ja, det fruktade p-ordet., Design docs hjälper dig att få feedback innan du slösar bort en massa tid på att implementera fel lösning eller lösningen på fel problem. Det finns mycket konst att få bra feedback, men det är för en senare artikel. För nu, låt oss bara prata specifikt om hur man skriver design doc och få feedback för det.
först och främst bör alla som arbetar med projektet vara en del av designprocessen. Det är okej om den tekniska ledningen slutar köra mycket av besluten, men alla borde vara inblandade i diskussionen och köpa in i designen., Så ” du ”i hela denna artikel är en riktigt plural” du ” som innehåller alla människor på projektet.
För det andra betyder designprocessen inte att du stirrar på whiteboard-teoriseringsidéerna. Känn dig fri att få händerna smutsiga och prototyp potentiella lösningar. Detta är inte detsamma som att börja skriva produktionskod för projektet innan du skriver en design doc. Gör inte så. Men du borde absolut gärna skriva någon hacky throwaway-kod för att validera en idé., För att säkerställa att du bara skriver undersökande kod, gör det till en regel att ingen av denna prototypkod blir sammanfogad till mästare.
Efter det, när du börjar få en uppfattning om hur du ska gå om ditt projekt, gör du följande:
- be en erfaren ingenjör eller teknisk ledning i ditt team att vara din granskare. Helst skulle det här vara någon som är väl respekterad och/eller bekant med problemets kantfall. Muta dem med boba om det behövs.
- gå in i ett konferensrum med en whiteboard.,
- beskriv problemet som du tar itu med till denna ingenjör (detta är ett mycket viktigt steg, hoppa inte över det!).
- förklara sedan genomförandet du har i åtanke, och övertyga dem om att detta är rätt sak att bygga.
gör allt detta innan du ens börja skriva din design doc kan du få feedback så snart som möjligt, innan du investerar mer tid och få fäst vid någon specifik lösning., Ofta, även om genomförandet förblir detsamma, kan din granskare påpeka hörnfall du behöver täcka, ange eventuella förvirringsområden och förutse svårigheter du kan stöta på senare.
sedan, efter att du har skrivit ett grovt utkast till din design doc, få samma granskare att läsa igenom det igen, och gummi stämpla det genom att lägga till deras namn som granskare i avsnittet titel och personer i design doc. Detta skapar ytterligare incitament och ansvarsskyldighet för granskaren.,
överväg att lägga till specialiserade granskare (t.ex. SREs och säkerhetsingenjörer) för specifika aspekter av konstruktionen.
När du och granskaren / recensenterna loggar ut kan du skicka design doc till ditt team för ytterligare feedback och kunskapsdelning. Jag föreslår tidsbundning denna återkopplingsinsamlingsprocess till ungefär 1 vecka för att undvika förlängda förseningar. Åta sig att ta itu med alla frågor och kommentarer människor lämnar inom den veckan. Lämnar kommentarer hängande = dålig karma.,
slutligen, om det finns mycket tvivel mellan dig, din granskare och andra ingenjörer som läser doc, rekommenderar jag starkt att konsolidera alla punkter i tvisten i diskussionsavsnittet i din doc. Ställ sedan in ett möte med de olika parterna för att prata om dessa meningsskiljaktigheter personligen.
När en diskussionstråd är mer än 5 kommentarer lång, flyttar till en personlig diskussion tenderar att vara mycket effektivare. Tänk på att du fortfarande är ansvarig för att göra det slutliga samtalet, även om alla inte kan komma överens.,
När jag pratade med Shrey Banga nyligen om detta lärde jag mig att Quip har en liknande process, förutom att ha en erfaren ingenjör eller teknisk ledning på ditt lag som granskare, föreslår de också att ha en ingenjör på ett annat lag granska doc. Jag har inte provat det här, men jag kan verkligen se det här som hjälper till att få feedback från personer med olika perspektiv och förbättra doktorns allmänna läsbarhet.
När du har gjort alla ovanstående, tid att komma igång med genomförandet!, För extra brownie poäng, behandla denna design doc som ett levande dokument som du implementerar designen. Uppdatera doc varje gång du lär dig något som leder till att du gör ändringar i den ursprungliga lösningen eller uppdaterar din scoping. Du kommer att tacka mig senare när du inte behöver förklara saker om och om igen för alla dina intressenter.
slutligen, låt oss få riktigt meta för en sekund: hur utvärderar vi framgången för en design doc?
Min kollega Kent Rakip har ett bra svar på detta: En design doc är framgångsrik om rätt AVKASTNINGEN av arbetet är gjort.,ts av den tekniska arkitekturen
X är den mest riskfyllda delen av den föreslagna arkitekturenX första att de-risk projektX är antingen inte är möjligt, eller mycket svårare än vad man ursprungligen avsetti början av denna artikel, vi sa att målet med en design doc är att se till att rätt arbete blir gjort., I exemplet ovan, tack vare denna design doc, istället för att slösa bort potentiellt månader bara för att avbryta detta projekt senare, har du bara spenderat 8 dagar. Verkar vara ett ganska framgångsrikt resultat för mig.
vänligen lämna en kommentar nedan om du har några frågor eller feedback! Jag skulle också gärna höra om hur du gör design docs annorlunda i ditt team.
att ge kredit där kredit beror, jag lärde mig mycket av ovanstående genom att arbeta tillsammans med några otroliga ingenjörer på Plaid(vi anställer! Kom och designa och bygga några söta tekniska system med oss) och Quora.,
om du gillar det här inlägget, följ mig på Twitter för fler inlägg på teknik, processer och backend-system.