Hur man skriver teknisk dokumentation

Välj en uppgift, en läsare och en enda källa till sanningen. Skriv sedan stegen med enkelt språk, testa dem med någon som inte skrev dem och ta bort allt som inte hjälper läsaren att bli klar med jobbet.

Innan du skriver

Bra teknisk dokumentation börjar innan första meningen. Välj först en uppgift. Skriv till exempel om att ”koppla en ny betalningsgateway”, inte om att ”dokumentera appen”. Då får du ett tydligt slutmål och sidan blir användbar.

Sedan behöver du veta vem läsaren är. En utvecklare behöver installationsanteckningar, kommandon och kantfall. En supportmedarbetare behöver symptom, kontroller och lösningar. En projektledare kan behöva status, beroenden och överlämningsanteckningar. En sida kan fungera bra för en av dem, eller misslyckas för alla tre.

Samla sedan in källan till sanningen. Det kan vara kod, ärenden, skärmdumpar, designanteckningar, loggar, en runbook eller en gammal manual som fortfarande har ett bra avsnitt. Om två källor säger olika, stanna upp och fråga vilken som gäller innan du börjar skriva utkastet.

Välj format innan du börjar skriva. En installationsguide, en referenssida och en felsökningssida behöver olika upplägg. För en styrenhet till ett skrivbord kan en installationsguide förklara parkoppling och kalibrering. En referenssida kan lista knappnamn och vad lamporna betyder. En felsökningssida kan ta upp en fastnad lyftmekanism eller en blinkande fellampa.

Hur man skriver teknisk dokumentation

• Skriv resultatet först. Säg vad läsaren kan göra när sidan fungerar. Exempel: ”I slutet kommer du att ha appen för testmiljö kopplad till Stripe.”
• Använd ett enkelt flöde: syfte, vad du behöver, steg, resultat, lösningar. Det håller läsaren i rörelse.
• Skriv en handling per steg. ”Öppna administratörskonsolen. Välj Fakturering. Välj Lägg till betalningsmetod.” Det är lättare att följa än ett långt stycke med fem verb.
• Använd exakta namn för knappar, fält, mappar, kommandon, felkoder och filnamn. Om skärmen säger Lägg till betalningsmetod, kalla inte om det till Nytt kort i dokumentet.
• Håll begreppen konsekventa. Om du skriver arbetsyta i steg 1, byt inte till projektområde i steg 4.
• Placera det troliga problemet bredvid steget som orsakar det. Om åtkomst ofta är problemet, säg det där. Exempel: ”Om knappen saknas, kontrollera att du har åtkomst som faktureringsadministratör.”
• Använd exempel som går att kopiera för programvara och kod. Visa kommandot, och visa sedan det förväntade resultatet direkt efter. Det hjälper läsaren att snabbt kontrollera sin egen skärm.
• Skriv korta stycken. En idé per stycke räcker. Om ett stycke har för många idéer, dela upp det i två.
• Ta bort allt som inte hjälper någon att bli klar med uppgiften. Bakgrund är bara nyttig om den förhindrar ett misstag.
• Lägg till nästa steg i slutet. Länka till exempel till test-sidan, felsökningssidan eller den del av installationen som kommer härnäst.

En enkel stegmall

Ett stabilt stegformat gör dokumentationen lätt att läsa när uppgiften blir krånglig. Använd den här formen för varje steg: handling, resultat, lösning om det behövs. Det fungerar för programvaruinstallation, projektöverlämning och kommandobaserade arbetsflöden.

Exempel för en utvecklarsida: ”Kör npm install. Du bör se att paketlistan uppdateras. Om det misslyckas, kontrollera att Node 20 är installerat.” Det ger läsaren något att göra, något att förvänta sig och något att kontrollera.

Före: ”Sedan hanterar du beroendeproblemet.” Efter: ”Kör npm install. Om du ser ett behörighetsfel, öppna terminalen igen som en användare med skrivåtkomst.” Den andra versionen tar längre tid att skriva och går snabbare att använda.

För en sida om en skrivbordsstyrenhet kan du skriva: ”Håll in upp- och ned-knapparna i tre sekunder. Displayen ska blinka en gång. Om den inte gör det, koppla ur styrenheten och försök igen.” Det är enkelt, testbart och konkret.

Vad bra teknisk dokumentation innehåller

En användbar sida följer oftast den här ordningen: titel, kort inledning, förutsättningar, steg, förväntat resultat, lösningar, nästa steg. Den ordningen fungerar eftersom den svarar på läsarens frågor i samma ordning som de dyker upp.

Titeln ska namnge uppgiften. Inledningen ska tala om för läsaren vem sidan är för och vad den täcker. Förutsättningarna ska bara lista det som stoppar framsteg, som ett konto, en kabel, en version eller en inloggning.

Stegen ska stå i den riktiga ordningen, inte i den ordning som låter smartast. Lägg bara in varningar där de behövs. Lägg till ett kort lösningsavsnitt för de vanligaste missarna. Avsluta med en tydlig slutpunkt, till exempel ett testkörning eller en överlämning.

För en sida om uppsättning av en betalningsgateway kan det se ut så här: ”Anslut Stripe till appen för testmiljö. Du behöver administratörsbehörighet och en testnyckel. Följ stegen för att klistra in nyckeln, spara inställningen och köra en testdebitering. Om testet misslyckas, kontrollera nyckeln och kontots behörigheter. Gå sedan vidare till sidan för webhook-inställning.”

Testa innan du publicerar

Lita inte på utkastet bara för att det låter bra för dig. Ge det till någon som inte skrev det. Be personen följa det utan hjälp. Se var den pausar, gissar eller backar tillbaka.

Om personen pausar kan sidan sakna en förutsättning eller ett litet installationssteg. Lägg till det steget nära den första plats där personen behöver det.

Om personen gissar är formuleringen otydlig. Byt ut ”ange rätt värde” mot det exakta fältnamnet, etiketten eller filsökvägen.

Om personen backar tillbaka är ordningen fel. Flytta steget tidigare, eller dela upp sidan så att läsaren inte behöver hoppa runt.

Försök att rätta till det förvirrande partiet, inte bara meningen runt det. Ibland är den riktiga lösningen en ny förutsättning, ett byte av skärmdump eller en andra sida.

För en snabb kontroll kan du köra igenom tools manual check. Om du behöver samma vana för fysiska instruktioner, jämför strukturen med this guide.

Det som oftast blir fel

Det vanligaste problemet är för mycket sammanhang och för lite handling. Läsaren behöver inte en historielektion innan knappnamnet.

En annan miss är att blanda olika uppgifter på samma sida. Installation, felsökning och referens konkurrerar om utrymmet. Dela upp dem när läsaren måste växla tankesätt.

Skärmdumpar blir snabbt gamla. Använd dem bara för skärmar som ändras sällan. När etiketter flyttar sig ofta, använd en kort markering eller en beskuren bild i stället för en helskärmsbild.

Vaga ord skapar också problem. Hoppa över ”enkel”, ”lätt” och ”bara”. De löser inte en fastnad driftsättning eller en saknad behörighet.

När en sida känns för lång, ta bort det onödiga först. Behåll stegen som leder läsaren till ett fungerande resultat.

Hur lång tid det tar

En kort hur man gör-sida kan ta 30 till 60 minuter om källan är ren och uppgiften är enkel.

En vanlig guide för mjukvaruinstallation tar oftast 2 till 4 timmar när du räknar in utkast, kontroll av stegen och redigering.

Ett större projektinnehåll med specialfall, skärmdumpar och granskningsrundor kan ta större delen av en dag.

Den långsamma delen är oftast att bevisa att stegen fungerar, inte att skriva dem. Om processen är stökig, skriv dokumentet medan du gör uppgiften. Då fångar du snabbt saknade klick, dolda antaganden och klumpiga formuleringar.

När en videoversion hjälper

En skriven sida är fortfarande bäst för sökning, referens och exakt text som går att kopiera. En video hjälper när uppgiften har många steg, skärmar som ändras eller återkommande supportfrågor. Det är vanligt vid introduktion, installation och praktiska arbetsmoment.

Om du redan har en monteringsanvisning eller en instruktionssida kan en kort filmad version ligga bredvid. Manual to Video gör om en befintlig manual till en animerad, textad steg-för-steg-film i dina varumärkesfärger och med din logotyp. Den kan också fungera med en QR-kod på manualen, kartongen, en produktsida eller en supportartikel.