cubussapiens.hu

Most olyan kedvem támadt (illetve olyan ingerek értek a közelmúltban), hogy úgy gondoltam, érdemes foglalkozni egy keveset írástechnikával is. Túlságosan nem értek a kérdéshez, éppen ezért, ha valaki úgy gondolja, valamivel nem ért egyet, esetleg kiegészítené az elhangzottakat, szépen megkérem, tegye meg!

Hihetetlen módon még a mi informatikusi életünkben is előfordul, hogy írnunk kell (méghozzá valamilyen emberi nyelven, nem számítógépnek). Sokszor kell bemutatni valaki másnak, hogy mit csináltunk, esetleg új fejlesztő jön a csapatban, és nem baj, ha nem kell sokáig mellette ülni, hogy felfogja, mivel dolgozik. Esetleg csak a főnökünknek/marketingeseknek/stb. kell elmondani, leírni, hogy mivel is foglalkozunk.

És sokaknál ezen a ponton eljött az Armageddon. Elvégre a mi a fenének szórakozzunk mi menet közben a dokumentálással, hiszen a kód úgyis magától értetődő, tisztább, mint az emberi nyelvek (elvégre a fordítók elég igényes állatfajt alkotnak, csak azt érti meg, amit tökéletesen mondunk neki, és esetleg félre is érthetik).

De az emberek jelentős része egyáltalán nem érti a programkódot, és a maradék számottevő része is szívesebben látja egy mondatban összefoglalva, hogy mit csinál az a kód (ami lehet, hogy akár csak öt sor). Azaz egyéb formában is le kell tudni írni, mit csinálunk. Amit hatékonyan csak az tud megcsinálni, aki ismeri is a rendszert (pl. aki írta). És utólag összeszedni, hogy miért pont egy adott megvalósítás mellett döntöttünk, kicsit nehéz megállapítani.

Aki még mindig kételkedik benne, hogy ez valóban probléma, annak javaslom megtekinteni a következő képet [[http://www.linuxkungfu.org/images/fun/geek/project.jpg|a kommunikációs félreértésekről]] szoftverfejlesztés kapcsán.

További probléma (még tiszta programkód esetén is!), hogy az, aki megpróbálja megérteni a programot, annak csak egy kis részét láthatja egyszerre. Tegye fel a kezét, akinek sikerült mondjuk az Eclipse jobban megírt részeit ránézésre megérteni: többszálú alkalmazás (hogy debug módban nehezebb legyen végigléptetni), tervezési minták (aminek általában az egyik fele valahol az API belsejében van, neked meg a túloldali interfészt kell csak megvalósítani), és több-kevesebb elérhető dokumentáció (Javadoc többnyire van, de az egy efféle rendszerben édeskevés).

Az egyedüli dolog, ami segíthet, az egy jól felkommentezett mintapélda (ha lehetséges megfelelően kis méretben megoldani), vagy még inkább megfelelő részletezettségű programozói dokumentáció (ezen azt értem, hogy ne kelljen 500 oldal dokumentációt áttanulmányozni a egy nézet írásához, de azért kellően részletes ahhoz, hogy az ötleteket megértsem, és tudjam, mikor melyik osztályhoz kell fordulni).

Igen, ez nehéz. Nem kicsit, nagyon.

Röviden összeszedve, bizony előfordul, hogy emberi nyelven kell írni, hosszabb-rövidebb szöveget. És ezt lassan ideje megtanulni is. Elméletileg az általános és középiskolában a magyarórákon a fogalmazástanításnak ez lenne az egyik célja: megtanuljunk írni.

És itt és most lezárnám ezt az első szakaszt, és átváltanék egy másikra: szeretnék néhány trükköt leírni, amik segítenek egy jobb minőségű írott szöveget összehozni.

Alapötlet: ismételhetőség

A tanszéken azt az ökölszabályt szokták mondani laborjegyzőkönyvekre, hogy szükség esetén abból egy alapfogalmakkal tisztában levő ember reprodukálni tudja a laborfeladatokat. Ezt jó ökölszabálynak tartom majdnem minden (technikai jellegű) dokumentációhoz, leíráshoz. Nem technikai leírásnál meg talán az lehetne a lényeg, hogy az olvasót valamilyen gondolatmeneten végigvezesse az író (esetleg adott érzetet keltsen benne).

Persze egy kicsit általánosítani kell ehhez a szabályt: legyen benne minden lényeges elem a reprodukáláshoz/felhasználáshoz, lehetőség szerint megfelelően struktúrálva.

Másik alapötlet: döntsd el, kinek írsz!

Természetesen nem döntheted el, ki fog elolvasni, amit írtál, de azért van egy célközönség. A célközönségről feltehetsz bizonyos ismereti szintet, de nem érdemes ezt túl magasra tenni a lécet, mert akkor kevesen tudják átugrani.

Érdemes egy nem túl magas szintet választani, és ehhez következetesen tartani magad az írás során.

Szenteljünk egy fejezetet a terület bemutatásának!

Egy átmeneti terület a strukturálás és a közönség megismerése között egy területbemutató fejezet írása. Ez a fejezet felhasználható arra, hogy a különböző előismeretű olvasók számára biztosítsuk azt a tudásszintet, amire szükségünk van a saját eredményeink bemutatásához.

Még akkor is hasznos, ha feltehető, hogy minden olvasó ért a területhez, ugyanis nagyon gyakran nem egységes a terminológia, különböző megközelítések léteznek. Ebben a fejezetben erre is ki lehet térni, ki lehet választani a terminológiát, és lehet hivatkozni egyéb művekre, amik a megértést segítik.

Legyen az írásnak eleje és vége!

Az írást lehetőleg a kontextus megadásával kell kezdeni. Ide tartozik az, hogy mi a motiváció a munkára, milyen problémát oldunk meg, esetleg egyéb megoldások miért nem alkalmazhatóak. Egyetemi házi feladatok, laborjegyzőkönyvek esetén ez többnyire nehézkes, hiszen a kontextust maga a feladat adja, és gyakran nem látszik, hogy miért pont így, de már önálló laboratórium, diplomamunka vagy TDK dolgozat esetén ez nagyon lényeges pont. Nagyon nehéz feladat bevezetést írni, hiszen egyfelől nem arról beszélsz, hogy mivel foglalkozol, hanem arról, hogy miért ezzel – és amikor már az ember olyan fázisba jut, hogy ír róla, ez gyakran triviálisnak tűnik, holott egyáltalán nem az.

További nehézség ennél a pontnál, hogy a célközönség előképzettsége ismeretlen. Így nem szabad túlságosan technikai módon bevezetni, mert akkor nem fogják elolvasni (mondván, túl bonyolult), nem fognak figyelni rá (nem érdekes), de a másik oldalra sem szabad átesni: a semmimondó bullshitre egy hozzáértő esetleg kicsit érzékenyen reagál.

Szintén nehéz kérdés a befejezés. Itt jön a második pont, ahol meg lehet próbálni eladni, ami készült. Értékelni kell, hogy mit tud, ami elkészült, legalább szőr mentén emlegetni, hogy mi az, nem, mások eszközei mit tudnak, esetleg írni azokról az írásokról, amit alapötletnek használunk.

A fejezetek önállóak – de csak részben

Az előbb említett bevezetésen és befejezésen kívül lehet beszélni még a lényegről is: nem mindegy, hogy milyen struktúrában kerül sor az eredmények részletezésére. A szomszédos fejezetek között megengedhető, hogy nagyobb logikai ugrás legyen, hiszen ezek önmagukban is értelmes, zárt elemek.

Amire viszont érdemes figyelni, hogy milyen utalásokat teszünk a fejezetek között. Visszautalni szabad, sőt célszerű is, hiszen itt lehet egyrészt a fontos elemeket újra hangsúlyozni (elvégre a korábbi fejezeteket már olvasták), az ismétlés pedig a hangsúlyozás egyik fontos eszköze. Nyilván itt is csínján kell bánni a dologgal, hiszen ha túl sokszor utalunk vissza, azzal pont a hangsúly megy el…

Az előreutalás nehezebb eset: mivel ezt még feltehetőleg nem olvasták, ezért a teljes gondolatot össze kell foglalni a hivatkozáshoz, előrehivatkozni csak azt lehet, hogy ezzel ott foglalkozunk részletesebben. Elvégre ez nem az internet, ahol össze-vissza lehet hivatkozgatni.

Ábrák, képek

Az ábrák, képek nagyon fontosak lehetnek: noha alapvetően szöveges tartalomról beszélek, egy-egy jól megválasztott ábra a megértést nagyban könnyítheti. Nyugodtan használjunk akár színes ábrákat is, de ne felejtsük el, hogy esetleg az olvasó csak fekete-fehér képet fog látni; és hasznos, ha a munkában szereplő képek, ábrák nagyjából egységes formátumúak – ha nagyon különböző stílusú ábrákat használunk (és látszólag ok nélkül), az amatőr benyomást kelt.

Felsorolások, táblázatok

Ez nagyon hasonló az előző lépéshez: bizonyos adatok szemléletesebbek felsorolásként vagy táblázatként. Ez az egyik gyenge pontom nekem is, ha visszanézi valaki a korábbi írásaimat itt az oldalon, látható, hogy hajlamos vagyok rosszul strukturált szösszeneteket összeszedni, címsorok is ritkán, de felsorolások, táblázatok szinte sohasem. Pedig az ilyesmi segíti az olvasót, hogy akár ugorjon is a szövegben, ne sorról sorra kelljen neki végigolvasnia, hogy mit tartalmaz a szöveg.

A [[Modelltranszformációk statikus analízise – TDK dolgozat|TDK dolgozatom]] érthetőségén sokat segített (nem mellesleg a terjedelmet is megdobta egy kissé :D), amikor a háromoldalas egybefüggő szöveget széttördeltem felsorolások segítségével. Rögtön jobban olvashatóvá vált a szöveg (már nem tudok példát mondani, az írás utolsó egy hete egy kissé összemosódik :)).

Példák

Hasonlóan fontos kérdés a példák használata. A jó példa egyszerű, hogy ne azzal menjen az idő, hogy a példa kontextusát megértsük, hanem azzal, hogy felfogjuk, ez hogyan kapcsolódik a máshol elhangzottakhoz. Ugyanakkor határozottan nem árt az sem, ha a példák kontextusa az írás során nagyjából ugyanaz marad.

A TDK dolgozatomban például a modelltranszformációkat Petri-hálók segítségével mutattam be, és később Petri-hálós példa segítségével lehetett volna teljesítmény-tesztelést végezni (ez eddig elmaradt, de legalább van mit írnom a diplomamunkámba 🙂 ). Természetesen hasznos lehet egyéb példák alkalmazása (például a kényszerkielégítési probléma bemutatásánál viszonylag kevéssé használható megközelítés a Petri-hálók használata), de lehetőség szerint érdemes minél inkább egy kontextusra hagyatkozni.

Írjuk meg előre a tartalomjegyzéket!

Legalább nagyjából. Nem kell kőbe vésni, amit leírunk, de azért tartsuk magunkat hozzá. Miért is jó ez? Mert ekkor végiggondoljuk, hogy miről fogunk írni, és milyen sorrendben. Itt lehet figyelembe venni a “függőségeket”, hiszen van olyan fejezet, aminek a megértéséhez egy másik fejezet elolvasása szükséges – ekkor nyilván ezt előrébb kell venni.

A fejezet címe nélkül is legyen érthető a fejezet tartalma!

Nagyon tipikus hibának tekinthető, hogy ami a fejezetcímben leírtak, azt a szövegben nem írják le még egyszer. Pedig érdemes. A fejezetcím valahogy nem a szöveg része, ezért amikor rájövök, hogy esetleg azt is el kell olvasnom (mármint még egyszer), kizökkentenek a szokásos olvasási ciklusaimból.Ezt a problémát nyomtatott szövegnél egyelőre relatíve ritkán látom, annál többször blogokban vagy levelezőlistákon. Ott más tényezők miatt még fontosabb lenne e szabály betartása. Gyűlölöm, amikor e-maileknél megkérdezi valaki, hogy a “Subject”-ben megjelölt tantárggyal kapcsolatban tud-e valaki valami információval szolgálni. Ennél még eggyel rosszabb, ha ezt programozási makróként $subject-tel jelöli. De ez most nem tartozik az írásom fő témájához, ezért be is fejezem.

Bekezdések

A kisebb részek megírásánál is oda kell figyelni. Az egyes bekezdések nagyjából egy-egy gondolatnak felelnek meg, így elég szerencsétlen a helyzet, ha ezek között nem megfelelő a kötés. Arra utal, hogy az egész témakör nincs rendesen körüljárva, illetve nem állt össze valami egységes rendszerbe az író fejében. Határozottan nem árt, ha egy bekezdésnek szerves folytatása az utána következő.

A jól összekötött bekezdések emiatt megfelelő irányba terelhetik az olvasó gondolatait olvasás közben, hiszen egy logikai láncot tükrözhet. Az összekötések kiválasztásában segítségünkre lehet a (akár matematikai) logika: ellentmondhatunk a korábbi bekezdésnek, következtethetünk belőle, esetleg kiegészíthetjük, és még sok minden egyebet tehetünk. Ha nagyon új gondolat következik, amit nem lehet a korábbiakhoz kapcsolni, akkor kell új fejezetet/szakaszt kezdeni, vagy a gondolatot máshova helyezni.

Alkalmazkodj a médium és a közönség stílusához!

Itt is bejön, hogy ismerd meg a közönséged, és kiegészül azzal, hogy tudd, hogy az adott médiumon mit szabad és mit nem. Egy blog például egy relatíve kötetlen műfaj: ott a legtöbb szabályt nem szükséges betartani, és a stílus is teljesen szabadon választott: ami neked tetszik, azt lehet.

Ugyanakkor egy házi feladat, dokumentáció vagy diplomamunka esetén a forma és a stílus nagyon kötött: nem engedheted meg magadnak a laza stílust vagy a poénkodást, és ezt rossz néven is veszik.

Ne ragaszkodj feltétlenül a szabályokhoz!

Természetesen előfordulhat olyan eset, amikor valamely szervezési szabály nem alkalmazható. Például házi feladatok esetén többnyire értelmetlen egy hosszú fejezetben bemutatni a területet, hiszen az értékelő tudja – ugyanakkor hasznos lehet leírni az eredeti feladatot, és az esetleges nem egyértelmű részek választott értelemzését (ami többé-kevésbé megfeleltethető a kontextus megadásának). Rövid írások esetén nem feltétlen érdemes a tartalomjegyzéket előre megírni, mert ilyenkor a tartalomjegyzék is gyakran felesleges lehet.

Ilyen esetekben nyugodtan hagyjuk figyelmen kívül a vonatkozó szabályt – de tudatosan! Tudjuk, hogy melyik szabályt szegjük meg, valamint azt is, hogy miért!

Egyéb apróságok

A legtöbb esetben valamilyen szinten kötött a forma (pl. oldalméret, betűméret, terjedelem), de ha mégsem, akkor is ésszel kell meghatározni az írás kinézetét. A túl széles sorok nehezen olvashatóak, de például monitoron a több hasáb is… A legtöbb normának megvannak a maguk okai, csak ezeket sehol sem oktatják, hogy mit érdemes, ill. hogyan. Érdemes utánanézni.

És a végére hagytam az adu ászt: helyesírás. Semmi nem képes úgy elrontani egy írott szöveget, mint a helyesírás. Az elgépelések, vesszőhibák, esetleg a súlyosabb nyelvtani hibák egytől egyig rontják a munka színvonalát. És a helyesírásellenőrzőkben nem szabad megbízni (és erre nem vonatkozik a szabály figyelmen kívül hagyásának lehetősége 🙂 ). Annak érdekében, hogy ez megfelelő legyen, lehetőleg többször el kell olvasni a szöveget, és az sem baj, ha más is elolvassa beadás előtt. Természetesen így is benn maradhatnak hibák, de nem mindegy, hogy mennyi. Ajánlom mindenki figyelmébe [[http://tompika.symbion.hu/2007/01/19/helyesiras/|Tompika vonatkozó blogbejegyzését]], illetve egész hasznos ötleteket szedtek össze az [[http://hu.opensuse.org/Seg%C3%ADts%C3%A9g:Ford%C3%ADt%C3%A1s#Helyes.C3.ADr.C3.A1s|OpenSuse honosítási]] oldalán.

Remélem, ez a lista hasznos így összeszedve, de ha bárki bármivel ki tudja egészíteni, esetleg azt mondja, hogy nincs igazam, szívesen meghallgatom. Mindenesetre ez most belőlem kikívánkozott.