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?
Du får lära dig en effektiv och systematisk metod och får personlig feedback på din nya manual!
