A stílusra és a hangvételre vonatkozó irányelvek

A .NET-dokumentumokat IT-üzemeltetők, fejlesztők és még sokan mások olvassák azért, hogy megismerkedjenek a .NET-tel, illetve segítséget kapjanak a napi munkájukhoz. Önnek olyan kiváló dokumentációt kell készítenie, amely közelebb viszi az olvasót a céljához. Útmutatónk segít ebben. Stíluskalauzunk a következő javaslatokat tartalmazza:

Használjon társalgási hangvételt

A következő bekezdés társalgási stílusban van megírva. Az utána következő már inkább akadémikus stílusú.

Megfelelő stílus

Azt a célunk, hogy a dokumentációnk társalgási hangvételű legyen. Az oktatóanyagok és a magyarázatok olvasása közben úgy kell éreznie, mintha beszélgetne a szerzővel. Informálisnak, társalgási hangvételűnek és informatívnak kell lennie a cikknek az Ön számára. Az olvasóknak úgy kell érezniük, mintha élőszóban hallanák azt, ahogyan a szerző elmagyarázza nekik a tudnivalókat.

Nem megfelelő stílus

Nem nehéz észrevenni a különbséget a társalgási stílus és a műszaki témákról szóló tudományosabb értekezésekben alkalmazott stílus között. Ezen anyagok is rendkívül hasznosak, azonban a szerzők dokumentációnkétól jelentősen eltérő stílusban írták meg az e típussal jellemezhető cikkeket. A tudományos folyóiratok olvasásakor az írás hangvétele és stílusa jelentékeny mértékben különbözik az általunk elvárttól. A tudományos cikkek egy nagyon száraz témát ismertetnek nagyon szárazon.

Írjon második személyben

A következő bekezdés második személyt használ. Az utána következő harmadik személyt használ. Kérjük, hogy második személyben írjon.

Megfelelő stílus

Úgy írja a cikket, mintha közvetlenül az olvasóhoz beszélne. Gyakran használjon második személyű alakokat (ahogyan ebben a két mondatban). A második személy nem jelenti azt, hogy állandóan az „Ön” névmást kell használnia. Közvetlenül az olvasónak írjon. Írjon felszólító mondatokat. Mondja el az olvasónak, hogy mit szeretne megtanítani neki.

Nem megfelelő stílus

A szerző a harmadik személyű írásmódot is választhatja. Ez esetben a szerzőnek valamilyen névmást vagy főnevet kell keresnie, hogy utalni tudjon az olvasóra. Az olvasót az ilyen harmadik személyű stílus általában kevésbé köti le, az ilyen cikk olvasása nem túlságosan élvezhető.

Aktív igealakokat használjon

Aktív igealakokkal írja meg a cikket. Az aktív igealakok azt jelentik, hogy a mondat alanya hajtja végre a mondatban foglalt cselekvést (az ige jelentését). Ellentéte a passzív fogalmazásmód. Ebben a mondat úgy van megszerkesztve, hogy a mondat alanyán végzi el valaki vagy valami a cselekvést. Hasonlítsa össze a következő két példát:

A fordítóprogram végrehajtható formátumúra alakította át a forráskódot.

A forráskód átalakításra került végrehajtható formátumra a fordítóprogram által.

Az első program aktív igealakokat használ. A második mondat passzívan van megfogalmazva. (Ez a két mondat újabb példával szolgál a kétféle stílusra).

Azért javasoljuk az aktív fogalmazásmódot, mert érthetőbb. A passzív megfogalmazású mondatok értelmezése nehezebb lehet.

Írás esetleg korlátozott szókincsű olvasók számára

A cikkek nemzetközi olvasóközönségnek szólnak. Sok olvasónak nem anyanyelve az angol, és nem feltétlenül rendelkeznek az Önéhez hasonló szintű szókinccsel.

De arról se feledkezzen meg, hogy műszaki szakembereknek ír. Azt bátran feltételezheti, hogy az olvasók tudnak programozni, és ismerik a programozás szakszókincsét. Az objektumorientált programozás, az objektum, a függvény és a metódus ismerős fogalom számukra. Nincs azonban az olvasóközönség minden tagjának egyetemi diplomája informatikából. Ha például az „idempotens” kifejezést használja, azt alighanem definiálnia kell, például így:

A Close() metódus idempotens, vagyis akárhányszor hívja is meg, ugyanaz lesz a hatása, mintha csak egyszer hívta volna meg.

Kerülje a jövő időt

A nyelvek egy részében nagyon másképpen használják a jövő időt, mint az angolban. A jövő idő használatával megnehezítheti a dokumentumok megértését. És a jövő idő használata esetén természetesen felmerül a „mikor?” kérdése is. Ha például azt írja, hogy „A PowerShell megismerése előnyére fog válni”, felvetődik az a kézenfekvő kérdés, hogy mikor fog előnyére válni. Mondja inkább egyszerűen azt, hogy a „PowerShell megismerése előnyére válik”.

Mi ez? És mire jó?

Ahányszor csak bevezet egy fogalmat, amely újdonság az olvasónak, először definiálja, és utána magyarázza el, hogy miért hasznos. Fontos, hogy az olvasó tudja, hogy miről van szó, mert csak így értheti meg az előnyeit (vagy akár a hátrányait).