Agil dokumentation tips #3: Den vanliga utvecklarmissen

Konkret abstrakt text

Utvecklare är hårt drillade i att skriva generisk kod. Jag tycker mig se att det färgar även hur utvecklare skriver dokumentation. Men är generisk text bra?

Fördelar med generisk text

Självklart är generisk text till viss del bra. Förmågan att lyfta blicken är användbar. Om du skriver modulär dokumentation, där du vill kunna återanvända vissa block på flera ställen i dokumentationen – kanske till och med för olika produkter – ja då gäller det att hålla tungan rätt i mun.

Då kan det vara lockande att skriva ”Så använder du produkten” istället för ”Så använder du Alfagrej” och ”Så använder du Betagrej”. Ska texten dessutom översättas så är det extra smidigt att generalisera, eftersom texten då bara behöver översättas en gång.

Men, det du ska ha klart för dig är att generaliseringen är smidig för dig. Inte för läsaren.

Nackdelar med generisk text

För läsaren är ordet ”produkt” en abstraktion, en variabel som ska bytas mot respektive produktnamn – Alfagrej, Betagrej, Gammagrej. Läsaren måste alltså själv stanna upp och i huvudet byta ut ”produkt” mot rätt namn. Det är alltid jobbigare för läsaren att tolka ”produkten” jämfört med ”Alfagrej”. Och ju fler generaliseringar du gör, desto mer svårläst blir texten.

När jag granskar texter är den här typen av formuleringar lite kluriga. För de är ju inte fel. Det är helt korrekt att skriva ”produkt”. Men korrekt är inte samma sak som bra.

Du kan se det som en glidande skala – en slider. Drar du åt höger blir det mer abstrakt, drar du åt vänster blir det mer konkret. Till höger hittar du ord som levande varelse eller material. Till vänster hittar du Fido eller björkträ.

Försök att dra din slider så långt åt det konkreta hållet som möjligt.

Vill du lära dig att skriva manualer?

Den 19 augusti släpper jag min nya webbkurs: Skriv en manual
Du får lära dig en effektiv och systematisk metod och får personlig feedback på din nya 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

Vad kostar en manual

Vad kostar en manual?

Tid är pengar. Den största kostnaden för teknisk dokumentation är ofta tiden som skribenten lägger ner. Visst kan olika slags verktyg kosta pengar. Om du dessutom skickar manualen på tryck

Illustrerad instruktion

6 olika sätt att skriva instruktioner

Det finns många olika sätt att skriva instruktioner. Ett format är inte nödvändigtvis bättre än ett annat. Flera faktorer styr vilken typ av instruktion som fungerar bäst:  personliga preferenser: vissa

Avslöja dina anonyma agenter

Häromveckan deltog jag i en skrivutmaning som ordnades av Sandra Muller. I fem dagar jobbade jag med att förbättra en befintlig text på engelska som jag själv hade skrivit. Det

Tvättråd instruktioner

Så skriver du bättre instruktioner

Instruktioner finns överallt. Alla är tyvärr inte bra. Vissa är rent av omöjliga att följa. Det är onödigt, eftersom det finns gott om knep att ta till för att skriva

skriv lättläst

Skriver du med absorptionsmetoden?

Distraherade läsare får sämre arbetsminne Dagens läsare är distraherade och splittrade i sin uppmärksamhet. De får därmed högst begränsade arbetsminnen. Därför behöver du hjälpa dem med att hålla den röda

Läsbarhetsindex för kontakt

Läsbarhetsindex skapar kontakt

Ambition räcker inte alltid Om du vill få något slags mått på hur lättläst din text är så kan du testa dess läsbarhetsindex. När jag började jobba med teknikinformation hade

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.