Engineering Insights
En viktig färdighet för alla mjukvaruingenjörer är att skriva tekniska designdokument (TDDs), även kallade engineering design docs (EDDs). Här i den här artikeln ger jag några råd om hur man skriver bra designdokument och vilka misstag man bör undvika.
En varning: Olika team kommer att ha olika standarder och konventioner för teknisk design. Det finns ingen branschgemensam standard för designprocessen, och det kan inte heller finnas, eftersom olika utvecklingsteam kommer att ha olika behov beroende på deras situation. Det jag kommer att beskriva är ett möjligt svar, baserat på min egen erfarenhet.
Låt oss börja med grunderna: Vad är ett tekniskt designdokument och hur passar det in i designprocessen?
Ett tekniskt designdokument beskriver en lösning på ett visst tekniskt problem. Det är en specifikation, eller ”design blueprint”, för ett mjukvaruprogram eller en funktion.
Den primära funktionen för en TDD är att kommunicera de tekniska detaljerna för det arbete som ska utföras till medlemmarna i teamet. Det finns dock ett andra syfte som är lika viktigt: processen att skriva TDD:n tvingar dig att organisera dina tankar och överväga varje aspekt av designen, vilket säkerställer att du inte har utelämnat något.
Tekniska designdokument är ofta en del av en större process som vanligtvis har följande steg:
- Produktkrav definieras. De representeras vanligtvis av ett dokument om produktkrav (PRD). I PRD-dokumentet anges vad systemet måste göra ur en användares eller utomstående aktörs perspektiv.
- Tekniska krav definieras. Produktkraven översätts till tekniska krav – vad systemet måste åstadkomma, men nu hur det gör det. Resultatet av detta steg är ett dokument om tekniska krav (TRD).
- Teknisk design. Detta innehåller en teknisk beskrivning av lösningen på de krav som skisserats i de föregående stegen. TDD är resultatet av detta steg.
- Genomförande. Detta är det steg där lösningen faktiskt byggs.
- Testning. Systemet testas mot PRD och TRD för att säkerställa att det faktiskt uppfyller de specificerade kraven.
Mellan vart och ett av dessa steg finns det vanligtvis en granskningsprocess för att säkerställa att inga misstag har gjorts. Om några fel, missförstånd eller tvetydigheter upptäcks måste dessa korrigeras innan man går vidare till nästa steg.
Denna process är mycket varierande; den uppsättning steg som anges här kommer att ändras från fall till fall. Till exempel:
- För mindre funktioner som inte innebär mycket komplexitet kommer steg 2 och 3 ofta att kombineras till ett enda dokument.
- Om funktionen innebär ett stort antal okända faktorer eller en viss nivå av forskning kan det vara nödvändigt att konstruera en proof-of-concept-implementation innan den tekniska designen färdigställs.
Den här processen sker också på olika skalor och granularitetsnivåer. Ett PRD / TRD / TDD kan gälla utformningen av ett helt system eller bara en enskild funktion. I de flesta miljöer är processen också cyklisk – varje design/implementeringscykel bygger på arbetet i den föregående.
Gränsen mellan TRD och TDD kan ibland vara lite suddig. Anta till exempel att du utvecklar en server som kommunicerar via ett RESTful API. Om målet är att överensstämma med ett redan etablerat och dokumenterat API är API-specifikationen en del av kraven och bör refereras i TRD. Om målet däremot är att utveckla ett helt nytt API är API-specifikationen en del av designen och bör beskrivas i TDD. (Kravdokumentet måste dock fortfarande specificera vad API:et försöker åstadkomma.)
Skrivning av TDD
Här i dag är det vanligt att skriva tekniska dokument i ett system för samarbetsdokument, t.ex. Google Docs eller Confluence; detta är dock inget absolut krav. Det viktiga är att det finns ett sätt för dina teammedlemmar att kunna kommentera dokumentet och påpeka fel och brister.
De flesta TDD:er är på mellan en och tio sidor. Även om det inte finns någon övre gräns för längden på en TDD kommer mycket stora dokument att vara både svåra att redigera och svåra för läsarna att ta till sig. Överväg att dela upp det i separata dokument som representerar enskilda steg eller faser av genomförandet.
Diagram är till hjälp; det finns ett antal online-verktyg som du kan använda för att bädda in illustrationer i dokumentet, till exempel draw.io eller Lucidchart. Du kan också använda offline-verktyg som Inkscape för att generera SVG-diagram.
Dokumentet ska vara grundligt; helst ska det vara möjligt för någon annan än TDD-författaren att implementera designen som den är skriven. Om designen till exempel specificerar en implementering av ett API bör varje API-slutpunkt dokumenteras. Om det finns subtila designval bör de nämnas.
Undervik vanliga skrivfel
Det vanligaste felet som jag stöter på i TDD:er är förmodligen brist på sammanhang. Det vill säga, författaren skrev ner, med så få ord som möjligt, hur de löste problemet; men de inkluderade ingen information om vad problemet var, varför det behövde lösas eller vilka konsekvenserna var av att välja just den lösningen.
Det är också viktigt att tänka på vem den troliga läsaren är och vilken nivå av förståelse de har. Om du använder en term som läsaren kanske inte känner till, var inte rädd för att lägga till en definition för den.
Det behöver knappast sägas att god grammatik och stavning är till hjälp. Undvik också frestelsen till ordlekar eller ”gulliga” stavningar; även om programmerare som klass tenderar att gilla att leka med språket har jag sett mer än ett fall där överdriven lättsinnighet slutade med att det kostade teamet slöseri med arbete på grund av missförstånd. Det är okej att använda tillfällig humor eller välja färgstarka, minnesvärda namn för funktioner och system, eftersom det hjälper människor att komma ihåg dem. Men låt inte din önskan att visa hur smart du är bli en distraktion.
När vi talar om namn, välj dem med omsorg; som Mark Twain en gång skrev: ”Välj rätt ord, inte dess kusin i andra hand”. Det finns en tendens för ingenjörer med dåligt ordförråd att använda samma generiska termer om och om igen för olika saker, vilket leder till överbelastning och förvirring. Att namnge en klass ”DataManager” är till exempel vagt och säger ingenting om vad den faktiskt gör. På samma sätt kan ett paket eller en katalog som heter ”utils” innehålla praktiskt taget vad som helst. Rådfråga en tesaurus om du behöver hitta ett bättre ord, eller ännu hellre en specialiserad synonymdatabas som WordNet.
TDD-mall
När du skriver en TDD kan det vara bra att börja med en standardmall. Följande är en mall som jag har använt i ett antal projekt. Observera att den här mallen bör anpassas vid behov; det står dig fritt att ta bort avsnitt som inte är tillämpliga, lägga till ytterligare avsnitt eller byta namn på rubrikerna när så är lämpligt.