Just in case or just for when?

Konfiguration av proppskåp

Mitt allra mest värdefulla och mest använda tekniska dokument är det som visas på bilden nedan. Det är förteckningen över vilken propp som hör till vilken del av huset. Den här lilla ”konfigurationsbeskrivningen” är superkortfattad men ändå så genialisk, vårt liv hade varit mycket krångligare utan den.  Vad är nyckeln till att skriva ett värdefullt dokument?

Konfiguration av proppskåp

Det korta svaret på den frågan är att skriva “just for when”, att du har ett tydligt syfte med ditt tekniska dokument. Motsatsen är att skriva för “just in case”, där du skriver för alla tänkbara situationer och läsare, vilket är ambitiöst och hedervärt men som tyvärr sällan slutar med ett användbart dokument.

Målgruppen – inte produkten – styr innehållet

Målgruppen för proppskåpsdokumentet är den som bor i huset, det vill säga jag.

Notera att dokumentet inte är proppskåpstillverkarens – eller ens elektrikerns – braindump. Här står inget om hur proppskåpet är uppbyggt, vilka spänningsnivåer som gör att huvudsäkringen bryts eller ens vilka färger på kablar som elektrikern har använt.

Fundera nu en liten stund över hur proppskåpstillverkarens manual till elektrikern skulle se ut. Rätt annorlunda va?

Trick: tänk på en person du känner

Du vet säkert redan att det är oerhört viktigt att veta vem du skriver för. Ett trick för att göra det enklare att komma till skott och skriva är att tänka ut personas baserade på verkliga personer som finns i din närhet. Om din kompis som är utvecklare skulle börja jobba hos er, vad behöver hon då veta om er arkitektur? Eller om din farfar ska använda er produkt, hur detaljerad behöver instruktionerna i manualen vara?

Personas-tricket gör att resultatet blir bättre och du kommer att märka att det plötsligt blir superlätt att skriva!

När ska personen använda dokumentet?

Du behöver inte bara veta vem du skriver för utan också när personen kommer att läsa dokumentationen. I vilken situation? För det kommer aldrig att hända att en människa plockar upp din produktbeskrivning på 120(0) sidor och läser den från A till Ö för att hen vill veta lite mer om produkten. Aldrig.

Läsaren har ett problem och hoppas att din dokumentation ska ge lösningen. Kanske behöver läsaren veta systemkrav, prestanda eller vilka egenskaper som går att ändra. Eller vilka moduler produkten är uppbyggt av. Då måste du ha skrivit dokumentet för att kunna lösa det problemet, annars är det ganska värdelöst.

Undvik fallgropen

En vanlig fallgrop här är att skriva ett dokument som förklarar allt om hur produkten fungerar och tänka att användaren ska läsa allt, förstå och sedan själv kunna tänka ut hur problemet bör lösas. Spoiler alert: det är en dålig idé. Du behöver hjälpa användaren mer än så.

Du behöver alltså ha ett tydligt scenario framför ögonen när du skriver. I fallet med proppskåpet är situationen: ”Användaren vill veta vilken propp hen ska slå av och på när hen ska installera ny diskmaskin och inte samtidigt råka stänga ner routern med tillhörande wifi”.

Paradoxen

Min tes är alltså att om du försöker skriva ett dokument som riktar sig till alla och som ska vara heltäckande och fungera i alla situationer, då kommer ditt dokument inte att fungera för någon.

Om du istället skriver för en smal målgrupp och för en eller flera tydliga situationer så finns så klart risken att du har missat en situation, eller en viss målgrupp. Men här kommer knorren. När du läser ett dokument där det tydligt står målgrupp och syfte och det inte riktigt stämmer med din situation, då kan du förmodligen ändå härleda viss information från det dokumentet, just tack vare att du VET vilken situation och användare det skrevs för. För det är lättare att göra den härledningen när alla korten tydligt ligger på bordet, än om allt är vagt, otydligt och abstrakt.

Sammanfattning

Dagens uppmaning är alltså:

  • Skriv för en tydlig person.
  • Skriv för en specifik situation.
  • Skriv ut vilken målgrupp och situation som dokumentet är skrivet för.

Läs vidare

Har din manual rätt fokus? Handlar din manual om användaren eller om produkten?
Läs mer om hur du skriver en användarcentrerad manual.

Dela på facebook
Dela på twitter
Dela på linkedin
Dela på email

Jag hjälper dig med metoder, kunskap och erfarenheter kring produktdokumentation så att den blir både effektiv och användbar.

Fler inlägg

Buffe med mat

Därför ska du skriva manualen som en buffé

Jag är en förespråkare av modulär teknisk dokumentation. Varför? För att det gör dokumentationen lättare att använda, lättare att skriva och framför allt lättare att uppdatera. Hur då? Modulärt julbord

Instruktioner för att laga soppa

User stories ger dig rätt instruktioner (del 2)

User stories visar vad er produkt faktiskt ska uträtta åt användaren. Eller snarare vad användaren vill göra. Du kan nu enkelt förstå vilka instruktioner som du behöver skriva. Välkommen till

Läsare av teknisk dokumentation

Fixa dokumentationen med user stories (del 1)

User stories kan ge dig en flygande start när du ska skriva teknisk dokumentation, särskilt manualer av olika slag. Det gäller oavsett om det är grundläggande manualer till slutanvändare, integrationsinstruktioner

Musfälla

Trick för att locka information ur utvecklare

Att få fram underlag till teknisk dokumentation är verkligen en utmaning. Själv har jag provat allt. Jag har mutat utvecklare med kakor. Intervjuat stressade projektledare. Filtrerat ofantliga mängder med utvecklingsärenden

Tips till dig som skriver lathund i affekt

Behöver dina kunder en lathund för er produkt? Eller behöver ni själva en intern lathund på kontoret för att komma tillrätta med reseräkningarna? Lathundar kan vara många olika saker. Allt

Gunilla Svanfeldt Omslag

Samtycke till marknadsföring

Vi lagrar informationen som du anger i formuläret för att kunna kontakta dig med nyhetsbrev, om uppdateringar och med erbjudanden. 

Markera kryssrutan i formuläret för att ge ditt samtycke till att vi skickar e-post till dig.

We use MailerLite as our marketing automation platform. By clicking below to submit this form, you acknowledge that the information you provide will be transferred to MailerLite for processing in accordance with their Privacy Policy and Terms of Service.