Ezeket ne rontsd el technical writerként: az IT-dokumentációírás 5 buktatója

Elavult, átláthatatlan információk, zavaros célközönség és bonyolult, félreérthető megfogalmazások? Mutatunk 5 buktatót, amelyet elkerülve nem fogják a dokumentáció miatt otthagyni a szoftvert a felhasználók.

Emlékszel, mit jelentett a Mézga család 30. századbeli rokonának szájából az, hogy „haszutmellémafor”? A történet szerint a jövőben használt újmagyar nyelven ez annyit tett, „használati utasítás mellékelve, ómagyar fordításban”. Vagyis Romhányi József zseniális történeteiben, ha létezik is fényposta, ebéd helyetti kapszula és láthatatlanná tévő szer, a szerző úgy érezte, az ultramodern eszközök mellé továbbra is kelleni fog egy világos leírás.

Egy jól megírt dokumentáció a mai szoftverek fejlesztőinek és felhasználóinak is sokat segít a megértésben. Hiszen ha egy eszközt nem kizárólag azok használnak, akik azt létrehozták – ami azért elég ritka –, akkor fontos világosan leírni, hogyan működik. Ha pedig nem elég tiszta egy szoftver dokumentációja, az nagyban elrontja az ügyfelek felhasználói élményét.

Április 15-én induló IT-dokumentációírás a gyakorlatban kurzusunkon a kód- és API-dokumentációtól kezdve a felhasználói útmutatókon át az agilis dokumentációs módszerekig gyakorlati feladatokon keresztül ismerheted meg a szoftverdokumentáció területeit. Előadónkat, Zsámboki Dávidot, a Revolut Senior Technical Writerét pedig arra kértük, szedje össze, mik a leggyakoribb hibák, és hogy lehet azokat megelőzni.

1. Elszigetelődés és rossz kommunikációs csatornák

Jellemző hiba, hogy a szoftverdokumentációt elhanyagolják, és nem tekintik a termék szerves részének, elszigetelve a technical writereket, akik így nem is mindig kapják meg a szükséges információkat. „Fejlődik a termék, döntések születnek, de azzal nem számolnak, hogy ahhoz, hogy a terméket valaki használni is tudja, le is kell azt dokumentálni” – magyarázza előadónk. Az is megesik, hogy már több verzióval frissült a szoftver, de a dokumentáció ezt még nem követte le, mert nekik nem szólt senki. Ezen egy egyszeri techwriter proaktívabb szerepvállalással tud segíteni.

Magyarul ne pusztán várjuk a feladatokat, hanem tudatosítsuk a kollégákban, hogy a termék része a szoftverdokumentáció, gyakran épp az a selling point, hogy egy szoftvert könnyű használni, mert jól el van magyarázva. Saját, fizetési szektoros példáját hozza fel: ha a termékfelelős ránéz a dokumentációra, és azt mondja, hogy a fejlesztőknek egy fizetési megoldást két hét implementálni a webshopunkba, majd találsz egy olyan dokumentációt, amire azt, hogy egy hét, akkor az utóbbit fogja választani.

Zsámboki Dávid szerint jó megoldás, ha a fejlesztés feladatainál beállítanak egy kötelezően kitöltendő mezőt, amely szerint egy ticketet nem lehet addig lezárni, amíg nincs eldöntve, hogy az igényel-e dokumentációt, és ha igen, az elkészült-e már. Emellett dedikált és kizárólagos kommunikációs csatornákat is érdemes felállítani termékek, termékcsoportok vagy részlegek szintjén, ahol ezek követhetők – tanácsolja. A legtöbb problémát ugyanis az át nem adott információk okozzák.

Ezért érdemes meghívót kérni azokra a meetingekre, ahol a fejlesztéssel kapcsolatos döntések elhangoznak. „Ha jön a negyedév vége, minden nagyobb projekt felelősével beszélek, hogy a következő negyedévben előreláthatóan mi igényel majd dokumentációt” – osztja meg. Így is szoktak lenni ad hoc feladatok, de ezzel már lehet tervezni, ráadásul a proaktivitás a kollégákban is pozitív képet alakít ki rólunk, hogy jelen vagyunk, és érdekelnek minket a cég termékei. Így nem fogják elfelejteni, hogy ott vagyunk, és érzik, hogy lehet ránk számítani. „Ott kell lenni a folyamatok közepén!”

2. Nem tisztázott célközönség

Egy fizetési megoldás dokumentációját például nem csak fejlesztők olvassák, hanem olyan termékfelelősök is, akiknek kell egy megoldás, hogy a netes szolgáltatásukért pénzt fogadhassanak el. Ha mindenütt csak technikai információkat kapnak, akkor a termékről az lesz a benyomásuk, hogy az túl komplex ahhoz, hogy megértsék – magyarázza. Tehát a dokumentációból kell egy nekik szóló változat is, amely közérthetően leírja a funkciókat, az időt, amire a számlára odaér az összeg, és hogy mennyi ideig tart integrálni egy rendszerbe. A fejlesztőknek szóló verzióban pedig már szó lehet az API-paraméterekről is.

A probléma, hogy sokszor nem definiált, kinek szánnak egy dokumentációt. „Így lesznek olyan információhalmazok, amit senki sem tud jól használni, hiszen nincs meghatározva, hogy melyik része kinek szól” – hangsúlyozza. Ha viszont megvan, kinek írjuk az anyagot, már az ő igényeikre lehet szabni. Zsámboki Dávid azt mondja, ő úgy szokta, hogy legyen egy termékáttekintés annak az értékajánlatáról, főbb funkcióiról, legyen egy másik rész, amelyik bemutatja, hogyan kell használni és integrálni, de ezt még mindig közérthetően, végül pedig egy kizárólag technikai rész. Ha egy oldalon is, de legyen tiszta, melyik tartalom kinek szól – summázza.

3. A szakzsargon túlzott használata

Az előző pontban leírt elkülönítés nyilván eltérő megfogalmazásokat is jelent. Egy üzleti partnernek nem írhatunk le bonyolult IT-s szakkifejezéseket, mert bezárja az egészet, egy fejlesztőnek viszont bizonyos keretek között már igen. Utóbbiaknál az lehet még a buktató, hogy bizonyos szavak alatt nem mindenki ugyanazt érti, ez területenként is változhat. A köteg (angolul batch) alatt például a szoftveresek csoportosított feladatokat, egyszerre feldolgozott adatokat, esetleg kötegelt fájlokat érthetnek, míg a hardverrel foglalkozók például egy memóriaköteget.

Ezeket tisztázni kell, vagy még jobb elkerülni a félreértésre lehetőséget adó szakzsargonokat. „Ez egy egyensúlykeresés, hiszen vannak előfeltételezéseim, hogy egy célközönség mit érthet, ugyanakkor lehetőleg ennek az alsó tudásszintjét érdemes megcélozni. Ha a fejlesztők a célközönség, akkor se feltétlenül az experteknek írjunk, hanem úgy, hogy a juniorok is megértsék!” – tanácsolja. Egy-két szakszó és többértelműség persze becsúszik, ezeknél adjunk magyarázatot, ha szükséges! Jó módszer még egy fogalomtár kialakítása, ami a cégen belül eltérően megnevezett dolgok ellen is hasznos – tanácsolja. Emellett érdemes másokat, akár más területről is megkérni, hogy nézzenek rá egy oldalra, és jelezzék, ha van rajta olyan, ami nekik nem érthető.

4. Strukturálatlanság és nehézkes navigáció

Fontos a könnyű navigáció a szövegen belül, és a témák között is. Előadónk azt mondja, van, hogy a program konkrét funkcióihoz vannak rendelve az oldalak, egy helpdesk jellegű dokumentációban klasszikus, navigációs sávval lehet böngészni, illetve előfordul, hogy simán pdf-ben, tartalomjegyzékkel adják oda az anyagot. Egy jó megoldás lehet a különböző tematikus terek létrehozása is, ahol azok között, és azon belüli oldalakon is lehet navigálni. A lényeg, hogy mindez konzisztens legyen, jól átláthatók legyenek a különböző termékcsoportokhoz és funkciókhoz köthető leírások.

Megeshet, hogy maga a felépítés nem logikus, ahogyan a felhasználók elé tesszük a szoftverdokumentáció egyes részeit. Bár juniorként sokan lehetnek, akik nem mernek abba beleállni, hogy strukturáljuk át az egészet, Zsámboki Dávid szerint érdemes lehet ezt megtenni, főleg, ha valaki szeretne előrébb lépni majd a karrierjében. „Én nagyon sokat nyertem azzal, hogy beleálltam abba, hogy ennek itt nincs értelme” – húzza alá. Ha rossz a navigáció, az embereknek a termékről lesz negatív véleménye, hiszen a felhasználók szemében annak egy fontos része a dokumentáció. Mindez elkerülhető, ha logikusan végiggondoljuk az ügyfélélmény folyamatát, és ez alapján világos tartalomjegyzéket készítünk. Egy ideális online anyagnál pedig, ha már a címsorokból, a szöveg elolvasása előtt látható, honnan hová tudunk eljutni.

Felidézi, hogy az első senior pozíciójában is egy olyan feladattal kezdett, ahol egy szöveghalmazt először navigálhatóvá kellett tenni. A fejlesztőknek ugyanis két napja volt a dokumentációra a funkció bevezetése után, ezért csak „szórták be az oldalakat”, nem volt benne struktúra vagy jelzés arra, melyik rész kinek szól. Ezért sorba vette, mi szól a felhasználóknak, a fejlesztőknek és az adminisztrátoroknak, majd utána azok alá még létrehozott alkategóriákat, hogy mindenki megtalálja, ami neki szól, majd azon belül is tudjon keresni.

Ideális esetben van már a cégnél egy logikus struktúra ezeknek a leírásoknak a rendszerezésére, ellenkező esetben viszont nekünk kell azt felhúzni. Az információarchitektúra, azaz az adatok rendezése ugyanis a tech writing szerves része, hangsúlyozza. A bejáratott struktúrát már nem érdemes gyakran átszabni, sőt: jó, ha a különböző termékekhez is hasonló rendszerben áll össze a magyarázat, hogy a felhasználók ne érezzék magukat elveszve.

5. Elavult vagy pontatlan információk

Ez lehet a belső kommunikációs csatornák hibája. Van, hogy nem szólnak arról, hogy időközben továbbfejlesztettek egy terméket, így a dokumentáció nem tudja ezt követni. Ez a gyakorlatban például integrációs problémákhoz vezethet azokkal a rendszerekkel, ahová például egy fizetési megoldás be van építve, ha a fejlesztők nem számolnak mondjuk egy emiatt bekerülő új vagy átalakított paraméterrel.

„A gyógyszer-, autó- és légiiparban ez életekbe kerülhet” – figyelmeztet. A frissítések nyomon követéséhez érdemes a CI/CD (folyamatos integrációs és szállítási) folyamatokba beiktatni, hogy értesítse a tech writert, ha például bekerült egy új paraméter, és azt beteszi mondjuk egy táblázatba. Emellett a dokumentációval foglalkozó kollégának is kell, hogy legyen egy szempontrendszere, mikor érdemes már egy anyagot – a fejlesztő bevonásával – átnézni, hogy naprakész-e. Akár olyan szempontból is, hogy azóta esetleg már logikusabb struktúrát használ.

Ám ennél mélyebb oka is lehet annak, ha a technical writer rossz, logikátlan, érthetetlen, nehezen használható forrásanyagot kap. „Ha nehezedre esik elmagyarázni valamit, akkor jó eséllyel valamit már a termék tervezésénél elrontottak” – magyarázza. „Sokszor úgy is ledokumentáltam, hogy próbáltam jelezni, hogy ennek így nincs értelme, majd az ügyfelektől kaptuk a visszajelzést, hogy nem értik. Ez a rosszabb verzió, itt is hasznos a proaktív hozzáállás.” A tech writer ugyanis egyfajta kapuőr, aki mondhatja azt, hogy valamit ebben a formában nem dokumentál le, mert annak így nincs értelme, és más sem fogja érteni, és emiatt el is fordulhat a szolgáltatásunktól.

Közös cél a senioritás

Zsámboki Dávid azoknak ajánlja az április 15-én induló képzését, akik már foglalkoznak technical writinggal, és fejlődnének, például azért, mert juniorként megcéloznák a senior szintet. Szerinte egy jó ugródeszkát nyújt, és olyan tapasztalatokat tud átadni, amelyek segítenek az anyaggal tudatosan foglalkozó résztvevőknek az előrejutásban. Emellett junior fejlesztőknek is hasznos lehet a két folyamat integrációjához.

Szerző: Tarnay Kristóf Ábel

Megosztás: