Guide för röst och tonfall
Många användare, t.ex. IT-tekniker och utvecklare, läser .NET-dokumenten både för att lära sig .NET och som referens i det dagliga arbetet. Ditt mål är att skapa bra dokumentation som hjälper läsaren på denna resa. Våra riktlinjer hjälper dig med det. Vår stilguide innehåller följande rekommendationer:
Använd en samtalston
Följande stycke är skrivet i samtalston. Det som följer är i ett mer akademiskt format.
Lämplig stil
Vi vill att vår dokumentation ska ha en samtalston. Det ska kännas som om du sitter och pratar med författaren när du läser någon av våra självstudier eller förklaringar. För dig ska upplevelsen vara informell, samtalsmässig och informativ. Läsarna ska känna sig som om de lyssnar på att författaren förklarar begreppen för dem.
Olämplig stil
Det är skillnad mellan en samtalsstil och den stil som man ser i mer akademiska beskrivningar av tekniska ämnen. Dessa resurser är användbara, men författarna har skrivit artiklarna med en helt annan stil än i vår dokumentation. När man läser en akademisk text har den ett helt annat tonfall och en mycket annorlunda skriftstil. Det känns som om man läser en tråkig text om ett tråkigt ämne.
Skriva i andra person
Följande stycke är i andra person. Det som följer är i tredje person. Skriv i andra person.
Lämplig stil
Skriv artiklarna som om du talar direkt till läsaren. Använd andra person ofta (som jag har gjort i dessa två meningar). Andra person innebär inte att du alltid ska använda ordet ”du”. Skriv direkt till läsaren. Skriv imperativa meningar. Berätta för läsarna vad du vill att de ska lära sig.
Olämplig stil
En författare kan också välja att skriva i tredje person. I den modellen måste författaren hitta något pronomen eller substantiv som kan användas när man syftar på läsaren. Läsaren upplever ofta att denna stil med tredje person är mindre engagerande och mindre behaglig att läsa.
Använd aktiv verbform
Använd aktiv verbform i artiklarna. Aktiv verbform innebär att subjektet i meningen utför åtgärden (verbet). Det skiljer sig från passivform där meningens ordföljd innebär att man agerar på subjektet i meningen. Jämför dessa två exempel:
Kompileraren omvandlade källkoden till en körbar fil.
Källkoden omvandlades till en körbar fil av kompileraren.
Den första meningen använder aktiv verbform. Den andra meningen är skriven i passivform. (Dessa två meningar ger ett annat exempel på de olika stilarna).
Vi rekommenderar aktiv verbform eftersom det är enklare att läsa. Passivform kan vara svårare att läsa.
Skriv för läsare som kanske har en begränsad vokabulär
Du når en internationell målgrupp med dina artiklar. Många av dina läsare har inte engelska som förstaspråk och kanske inte har den vokabulär du har på engelska.
Men du skriver ändå för tekniska experter. Du kan förutsätta att dina läsare har programmeringskunskap och den specifika vokabulär som gäller programmeringstermer. Objektorienterad programmering, klass och objekt, funktion och metod är välkända begrepp. Men det är kanske inte alla som läser dina artiklar som har en formell examen i datavetenskap. Termer som idempotent kan till exempel behöva definieras om du använder den:
Close()-metoden är idempotent, vilket innebär att du kan anropa den flera gånger och effekten är likadan som om du bara anropade den en gång.
Undvik futurum
På vissa icke-engelska språk skiljer sig begrepp i futurum från engelska. Det kan bli svårare att läsa dina dokument om du använder futurum. När du använder futurum blir dessutom den uppenbara frågan: ”När?”. Om du skriver ”Att lära sig PowerShell kommer att vara bra för dig” – ställer sig läsaren frågan: ”När kommer det att vara bra?” Istället skriver du helt enkelt ”Att lära sig PowerShell är bra för dig”.
Det är som det är.
När du presenterar ett nytt begrepp för läsaren, definierar du först begreppet. Därefter kan du förklara varför det är användbart. Det är viktigt för läsaren att förstå vad något är, innan man kan se dess fördelar (eller motsatsen).