Veiledning for stemme og tone

En rekke ulike personer, deriblant IT-ansatte og utviklere, leser .NET-dokumentene både for å lære seg .NET, og for å bruke det i det daglige arbeidet. Målet er å opprette flotte dokumenter som hjelper leseren på veien. Disse retningslinjene bidrar til dette. Stilguiden inneholder følgende anbefalinger:

Bruk en uformell tone

Følgende avsnitt er skrevet i en uformell stil. Avsnittet etter har en mer akademisk stil.

Passende stil

Vi vil at dokumentasjonen skal ha en uformell tone. Du skal kunne føle at du har en samtale med forfatteren når du leser en av opplæringene eller forklaringene. Teksten skal ha en uformell og informativ stil. Leserne skal føle at de lytter til forfatteren mens han eller hun forklarer begrepene for dem.

Upassende stil

Man ser kanskje kontrasten mellom en uformell stil og den stilen man finner når man behandler tekniske emner på en mer akademisk måte. Disse ressursene er veldig nyttige, men forfatterne har brukt en veldig annerledes stil når de har skrevet disse artiklene, sammenlignet med dokumentasjonen vår. Når man leser et akademisk tidsskrift, finner man en veldig annerledes tone og skrivestil. Man føler at man leser et veldig tørt utdrag fra et veldig tørt emne.

Skriv i andre person

Følgende avsnitt bruker andrepersonstilen. Avsnittet etter bruker tredjepersonstilen. Skriv i andre person.

Passende stil

Skriv artiklene dine som om du snakker direkte til leseren. Bruk andrepersonstilen ofte (slik jeg har gjort i disse to setningene). Andre person betyr ikke alltid at du bruker ordet «du». Skriv direkte til leseren. Skriv imperativsetninger. Fortell leseren det du vil at vedkommende skal lære.

Upassende stil

En forfatter kan også velge å skrive i tredje person. I denne modellen må forfatteren først finne et pronomen eller substantiv som skal brukes til å referere til leseren. Lesere synes ofte at tredjepersonsstilen er mindre engasjerende og fornøyelig å lese.

Bruk aktiv stemme

Skriv artiklene med aktiv stemme. Aktiv stemme betyr at subjektet i setningen utfører handlingen (verbet) i denne setningen. Dette står i kontrast til passiv stemme, der setningen er ordnet slik at det blir handlet etter subjektet i setningen. Sammenlign disse eksemplene:

Kompilatoren transformerte kildekoden til en kjørbar fil.

Kildekoden ble transformert til en kjørbar fil av kompilatoren.

Den første setningen bruker aktiv stemme. Den andre setningen ble skrevet i passiv stemme. (Disse to setningene er enda et eksempel på hver av stilene).

Vi anbefaler aktiv stemme fordi den er lettere å lese. Passiv stemme kan være vanskeligere å lese.

Skriv for lesere som kan ha et begrenset vokabular

Du når en internasjonal målgruppe med artiklene. Mange av leserne har kanskje ikke norsk som morsmål, og har ikke det samme norske engelske vokabularet som du har.

Du skriver imidlertid fremdeles for tekniske arbeidere. Du kan anta at leserene har kunnskap om programmering og innehar et bestemt ordforråd med programmeringstermer. Objektorientert programmering, klasse og objekt, funksjon og metode er kjente termer. Men ikke alle som leser artiklene, har en formell utdanning innen informatikk. Termer som «idempotent» må sannsynligvis defineres hvis du bruker dem, for eksempel:

Close()-metoden er idempotent, noe som betyr at du kan kalle den flere ganger, og effekten er den samme som om du kalte den én gang.

Unngå bruk av fremtidsform

Fremtidskonseptet har ikke samme betydning på noen ikke-engelske språk som på engelsk. Bruk av fremtidsform kan gjøre dokumentene vanskeligere å lese. I tillegg, når du bruker fremtidsform, blir det naturlig å spørre om når. Hvis du sier «Det blir bra for deg å lære PowerShell», lurer leseren naturligvis på når det blir bra. I stedet kan du si «Det er bra for deg å lære PowerShell».

Hva er det? Hva så?

Når du introduserer et nytt begrep for leseren, må du definere begrepet og på dette tidspunktet forklare hvorfor det er nyttig. Det er viktig for leseren å forstå hva noe er før de kan forstå fordelene med det (eller det motsatte).