Kielen ja sävyn ohjeet

Erilaiset ihmiset, mukaan lukien IT-ammattilaiset ja kehittäjät, lukevat .NET-ohjeistuksia niin .NETin oppimisessa kuin sen käyttämisessä tavallisessa työssään. Sinun tehtäväsi on luoda toimivat ohjeet, jotka auttavat lukijaa työssään. Ohjeemme auttavat sinua siinä. Tyylioppaassamme annetaan seuraavat suositukset:

Käytä keskustelevaa sävyä

Seuraava kappale on kirjoitettu keskustelevalla tyylillä. Sitä seuraava kappale on kirjoitettu akateemisempaan sävyyn.

Ohjeiden mukainen esimerkki

Haluamme, että ohjeistuksen sävy on keskusteleva. Opetusohjelmien ja selitysten lukijalle pitäisi tulla sellainen olo, että hän keskustelee suoraan kirjoittajan kanssa. Hänelle tulisi jäädä tekstistä epämuodollinen, keskusteleva ja ja informatiivinen vaikutelma. Tekstin tulisi kuulostaa siltä, kuin lukija kuuntelisi kirjoittajan selitystä eri aiheista.

Ohjeiden vastainen esimerkki

Keskustelutyylin sekä esimerkiksi teknisiä aiheita käsittelevissä akateemisissa teksteissä tavattavan tyylin välillä havaitaan suuri kontrasti. Viimeksi mainitun kaltaiset resurssit ovat hyödyllisiä, mutta niissä käytettävä tyyli poikkeaa merkittävästi ohjeistuksessamme preferoidusta tyylistä. Lukiessaan akateemista julkaisua lukija kohtaa hyvin erilaisen sävyn ja kirjoittamistyylin. Syntyy vaikutelma ikävystyttävästä aiheesta, joka on vielä esitetty ikävystyttävällä tavalla.

Kirjoita toisessa persoonassa

Seuraavassa kappaleessa käytetään toista persoonaa. Sitä seuraavassa kappaleessa käytetään kolmatta persoonaa. Käytä toista persoonaa.

Ohjeiden mukainen esimerkki

Kirjoita artikkelisi ikään kuin puhuisit suoraan lukijalle. Käytä toista persoonaa (kuten näissä kahdessa virkkeessä). Et välttämättä tarvitse toisen persoonan käyttöön sinä-pronominia. Pyri kirjoittamaan suoraan lukijalle. Voit kirjoittaa virkkeet käskymuodossa. Kerro lukijalle, mitä haluat tämän oppivan.

Ohjeiden vastainen esimerkki

Kirjoittaja voi päättää kirjoittaa tekstinsä myös kolmannessa persoonassa. Tässä mallissa kirjoittajan täytyy käyttää pronominia tai substantiivia viitatessaan lukijaan. Lukijan mielestä kolmannen persoonan käyttö voi tehdä tekstistä vähemmän kiinnostavan ja vähemmän miellyttävän lukea.

Kirjoita aktiivimuodossa

Kirjoita artikkelit aktiivimuodossa. Aktiivimuoto tarkoittaa sitä, että virkkeen subjekti suorittaa virkkeen kuvaaman toiminnan (verbin). Aktiivimuodon vastakohta on passiivimuoto, jossa lauseen rakenne on sellainen, että virkkeen subjekti onkin toiminnan kohde. Vertaile näitä kahta esimerkkiä:

Kääntäjä muunsi lähdekoodin suoritettavaksi tiedostoksi.

Lähdekoodi muunnettiin suoritettavaksi tiedostoksi kääntäjän toimesta.

Ensimmäinen virke on aktiivimuotoinen. Toinen virke kirjoitettiin passiivimuodossa. (Myös edellä olevat lauseet toimivat esimerkkeinä kummastakin tyylistä).

Suosittelemme käyttämään aktiivimuotoa, koska sitä on helpompi lukea. Passiivimuoto voi tehdä tekstistä vaikealukuisen.

Kirjoita lukijoille, joilla voi olla rajallinen sanasto

Kirjoitat artikkeleita kansainväliselle yleisölle. Kaikki lukijat eivät osaa englantia yhtä hyvin, ja heidän sanavarastonsa voi olla suppeampi.

Toisaalta kirjoitat kuitenkin teknisten alojen ammattilaisille. Voit olettaa lukijoiden tietävän laajasti ohjelmoinnista ja tuntevan ohjelmointitermit myös englanniksi. Object Oriented Programming, Class sekä Object, Function ja Method ovat heille tuttuja termejä. Kaikilla artikkelin lukijoilla ei kuitenkaan ole varsinaista tietotekniikan tutkintoa. Idempotent (idempotentti) on esimerkki termistä, joka kannattaa määritellä, jos käytät sitä. Esimerkki:

The Close() method is idempotent, meaning that you can call it multiple times and the effect is the same as if you called it once. (Metodi on idempotentti, eli vaikutus on sama riippumatta siitä, montako kertaa toiminto suoritetaan.)

Vältä futuurin käyttöä

Futuuria eli tulevaa aikamuotoa ei kaikissa kielissä ymmärretä samalla tavalla. Futuurin käyttö voikin tehdä ohjeistuksesta vaikealukuisen. Futuurin käyttö herättää lisäksi lukijassa usein kysymyksen siitä, milloin kuvailtu asia tapahtuu. Jos siis kirjoitat ”PowerShellin oppimisesta tulee olemaan sinulle hyötyä”, lukijalle herää heti kysymys siitä, milloin siitä on hyötyä. Käytä mieluummin ilmaisua ”PowerShellin oppiminen on hyödyllistä.”

Mitä tarkoitat ja mitä siitä?

Kun esittelet lukijalle uuden asian, määrittele se ensin ja kerro vasta sitten, miksi siitä on hyötyä. Lukijalle on tärkeää ymmärtää ensin, mistä on kysymys. Vasta sen jälkeen hän voi ymmärtää asian hyödyt (tai haitat).