A szoftver dokumentációja csupán egy cikkekből álló gyűjtemény. De ezeket is ki tudják kergetni a világból. Először sokáig keresed a szükséges útmutatót. Aztán próbálod megérteni a nehezen érthető szöveget. Azt csinálod, amit írtak, de a probléma nem oldódik meg. Másik cikket keresel, idegeskedsz... Egy óra múlva pedig feladod, és távozol. Így működik a rossz dokumentáció. Mi teszi ilyenné, és hogyan lehet ezt megjavítani — olvasd el lentebb.
A régi dokumentációnknak sok hiányossága volt. Már közel egy éve átdolgozzuk, hogy a fent leírt forgatókönyv ne érintse ügyfeleinket. Nézd meg, és .
1. probléma: Nehezen érthető, rosszul megírt cikkek
Ha a dokumentációban nem lehet megérteni, mi értelme van? De senki sem ír szándékosan nehezen érthető cikkeket. Ezek abból adódnak, amikor a szerző nem gondol az olvasókra és a célra, ízléstelenségeket ír, és nem ellenőrzi a szöveget a hibák miatt.
- Olvasói közönség. Cikk írása előtt figyelembe kell venni az olvasók tudásszintjét. Logikus, hogy egy kezdőknek szóló cikkben nem hagyhatók ki az alaplépések, és a technikai kifejezéseket nem szabad magyarázat nélkül hagyni, míg egy ritka funkcióval foglalkozó szakmai cikkben érdemes kibővíteni a PHP szó jelentését.
- Cél. További fontos dolog, amivel érdemes előre foglalkozni. A szerzőnek világos célt kell kitűznie, meg kell határoznia a cikk hasznos cselekvését, és el kell döntenie, mit fog tenni az olvasó a cikk elolvasása után. Ha ezt nem teszik meg, a cikk leírása csupán leírás marad.
- Felesleges információk és hibák. Sok felesleges információ és hivatalos nyelvezet, hibák és elgépelések rontják a megértést. Még ha az olvasó nem is nyelvtan spicli, a hanyagság a szövegben elriaszthatja.
Vedd figyelembe a fenti tanácsokat, és a cikkek világosabbá válnak — garantáljuk. Ha még jobbat szeretnél csinálni, használd a .
2. probléma: A cikkek nem válaszolnak minden kérdésre
Rossz, ha a dokumentáció nem tart lépést a fejlesztéssel, nem válaszol a valós kérdésekre, a benne lévő hibák évekig megoldatlanok maradnak. Ezek a problémák nem annyira a szerző felelőssége, hanem a vállalaton belüli folyamatok szervezésének.
A dokumentáció nem tart lépést a fejlesztéssel
A funkció már elérhető, a marketing tervezi, hogy nyilvánosságra hozza, és eközben kiderül, hogy a dokumentációban még mindig nincs új cikk vagy fordítás. Emiatt néha el kellett halasztanunk a kiadást. Akármennyit kérjük is mindenkit, hogy időben adják át a feladatot a műszaki íróknak, ez nem fog működni. Ha a folyamatot nem automatizáljuk, a helyzet meg fog ismétlődni.
Változtatásokat hajtottunk végre a YouTrack-en. A feladat, hogy cikket írjunk az új funkcióról, abban a pillanatban érkezik a műszaki íróhoz, amikor a lehetőségeket tesztelni kezdik. Ekkor a marketing is értesül róla, hogy felkészülhessen a promócióra. Az értesítések a vállalati Messenger, a Mattermost segítségével is megérkeznek, így egyszerűen lehetetlen lekésni a fejlesztőktől érkező híreket.
A dokumentáció nem tükrözi a felhasználói igényeket
Hozzászoktunk ahhoz, hogy így dolgozunk: a funkció megjelent, mi beszámoltunk róla. Leírtuk, hogyan aktiválható, deaktiválható, és hogyan végezhető el a finomhangolás. De mi van akkor, ha az ügyfél úgy használja a szoftverünket, ahogy nem is gondoltuk? Vagy hibák merülnek fel, amelyekre nem gondoltunk?
Ahhoz, hogy a dokumentáció a lehető legteljesebb legyen, ajánlott elemezni a támogatási kéréseket, a tematikus fórumokon feltett kérdéseket, a keresőkben leadott kereséseket. A legnépszerűbb témákat át kell adni a műszaki íróknak, hogy kiegészítsék a meglévő cikkeket vagy újakat írjanak.
A dokumentáció nem fejlődik
Nehéz mindent egyszerre tökéletesen megcsinálni, hibák így is lesznek. Lehet bízni a visszajelzésekben az ügyfelektől, de valószínű, hogy nem fognak minden elírásról, pontatlanságról, érthetetlen vagy meg nem található cikkről beszámolni. Az ügyfeleken kívül a dokumentációt az alkalmazottak is olvassák, tehát ők is látják ezeket a hibákat. Ezt kihasználhatjuk! Csak olyan körülményeket kell létrehozni, amelyekben könnyen be lehet számolni a problémáról.
Van egy csoportunk a belső portálon, ahol az alkalmazottak megjegyzéseket, javaslatokat és ötleteket adhatnak a dokumentációval kapcsolatban. Szükség van egy cikkre, de az nincs? A tesztelő észrevett egy pontatlanságot? A partner a fejlesztési menedzsereken keresztül panaszt tett a hibák miatt? Mindez ebbe a csoportba! A műszaki írók azonnal javítanak valamit, átvisznek dolgokat a YouTrack-ra, vagy elgondolkodnak rajtuk. Hogy a téma ne süllyedjen el, időnként emlékeztetjük őket a csoport létezésére és a visszajelzés fontosságára.
3. probléma. A szükséges cikket sokáig keresni kell
Egy cikk, amit nem lehet megtalálni, semmiben sem jobb, mint egy cikk, ami nem létezik. A jó dokumentáció mottója legyen a „Könnyen kereshető, könnyen megtalálható” kifejezés. Hogyan érjük el ezt?
Rendezze struktúráját és határozza meg a téma választásának elveit. A struktúrának a lehető legegységesebbnek kell lennie, hogy az olvasó ne gondolkodjon azon, hogy „Hol találom ezt a cikket?”. Összességében két megközelítés létezik: az interfész és a feladatok szerint.
- Az interfészből. A tartalom megismétli a panel szekcióit. Így volt ez az ISPsystem régi dokumentációjában.
- A feladatokból. A cikkek és szekciók nevei tükrözik a felhasználók feladatait; a címekben szinte mindig vannak igék és válaszok arra a kérdésre, hogy „hogyan kell elvégezni”. Jelenleg áttérünk erre a formátumra.
Bármilyen megközelítést is választ, győződjön meg róla, hogy a téma megfelel a felhasználók kérdéseinek, és úgy van körülírva, hogy a felhasználó biztosan megoldja a problémáját.
Központosított keresés beállítása. Az ideális világban a keresésnek működnie kell, még akkor is, ha hibázik az írásban vagy a nyelvben. A Confluence-ban a keresésünk még nem tud ezzel örömet szerezni. Ha sok terméke van, és a dokumentáció általános, igazítsa a keresést ahhoz az oldalhoz, ahol a felhasználó tartózkodik. A mi esetünkben a főoldalon a keresés minden termékre működik, de ha már egy adott szekcióban van, akkor csak a benne lévő cikkekre korlátozódik.
Tartalom és „kenyérmorzsák” hozzáadása. Jó, ha minden oldalon van menü és kenyérmorzsák — a felhasználó útja az aktuális oldalhoz, lehetőséggel, hogy visszatérjen bármelyik szintre. Az ISPsystem régi dokumentációjában ki kellett lépni a cikkből, hogy elérjük a tartalmi listát. Ez kényelmetlen volt, ezért a újnál ezt kijavítottuk.
Hozza létre a hivatkozásokat a termékben. Ha az emberek újra és újra ugyanazzal a kérdéssel keresnek támogatást, érdemes egy javaslatot hozzáadni a felhasználói felülethez a megoldással. Ha vannak adatai vagy megértése arról, hogy a felhasználó mikor találkozik problémával, akkor értesítheti őt hírlevéllel is. Ezzel gondoskodik róla, és leveszi a terhet a támogatásról.
Jobbra az ugróablakban van egy hivatkozás a DNSSEC beállításáról szóló cikkre az ISPmanager domainkezelő szekciójában
Állítson be keresztlinkeket a dokumentációbanA cikkek, amelyek összefüggésben állnak egymással, 'linkelni' kell. Ha a cikkek egy sorozatot alkotnak, mindenképpen adjunk minden szöveg végére előre és hátra mutató nyilakat.
Valószínű, hogy az ember először nem nálad keresi a kérdésére a választ, hanem a keresőben. Beteges, ha technikai okokból nincsenek linkek a dokumentációhoz. Tehát gondoskodj a keresőoptimalizálásról.
4. probléma. Elavult tördelés zavarja az észlelést
A rossz szövegek mellett a dokumentációt a dizájn is meg tudja rontani. Az emberek megszokták, hogy jól tördelődő anyagokat olvasnak. A blogok, közösségi oldalak, médiák — az összes tartalom nemcsak szép, hanem olvasóbarát is. Ezért könnyen megérthetjük azt a fájdalmát annak, aki szöveget lát, mint az alábbi képen.
Ebben a cikkben annyira sok a képernyőkép és a kiemelés, hogy azok nem segítenek, hanem csak zavarják az észlelést (a kép kattintható)
Nem szabad a dokumentációból hosszú olvasmányt csinálni sok effektussal, de az alapvető szabályokat figyelembe kell venni.
Tördelés. Határozd meg a fő szöveg szélességét, betűtípust, méretet, címsorokat és margókat. Vonj be egy designerszakembert, és ha elfogadod a munkát, vagy önállóan is meg tudod oldani, olvasd el Artyom Gorbnova "Tipográfia és tördelés" című könyvét. Ez csak egy nézőpont a tördelésről, de teljesen elég.
Kiemelések. Határozd meg, mi igényel hangsúlyt a szövegben. Ez általában az interface-ben lévő út, gombok, kódbeillesztések, konfigurációs fájlok, 'Figyelj' blokkok. Határozd meg, hogy ezek az elemek hogyan legyenek kiemelve és rögzítsd a szabályzatban. Ne feledd, hogy minél kevesebb kiemelés, annál jobb. Ha sok van belőlük, a szöveg zajos lesz. Még a szavak is zajt okoznak, ha túl gyakran használják őket.
Képernyőképek. Egyeztess a csapattal, mely esetekben szükségesek a képernyőképek. Nincs szükség minden lépés illusztrálására. A sok képernyőkép, beleértve az egyes gombokat is, zavarja az észlelést és rontja a tördelést. Határozd meg a méretet, valamint a kiemelések és a feliratok formátumát a képernyőképeken, rögzítsd a szabályzatban. Ne feledd, hogy az illusztrációknak mindig meg kell felelniük a leírtaknak és aktuálisnak kell lenniük. Megint csak, ha a termék rendszeresen frissül, nehéz lesz követni mindent.
A szöveg hossza. Kerülje el a túl hosszú cikkeket. Törje őket részekre, és ha ez lehetetlen, adjon hozzá egy tartalomjegyzéket horgonyzó linkekkel a cikk elejéhez. Egy egyszerű módszer a cikk vizuális lerövidítésére az, ha a műszaki részleteket, amelyek csak szűk kör számára relevánsak, spoilerbe rejti.
Formátumok. Kombináljon több formátumot a cikkekben: szöveg, videó és képek. Ez javítja a megértést.
Ne próbálkodjon a problémák eltakarásával szép formázással. Őszintén, mi is azt reméltük, hogy a „csomagolás” megmenti a elavult dokumentációt – de nem így lett. A szövegekben annyi vizuális zaj és felesleges részlet volt, hogy a normák és az új formátumok tehetetlenek voltak.
Sok minden a fentiek közül attól függ, hogy mely platformot használja a dokumentációhoz. Nálunk például ez a Confluence. Ezen is dolgozni kellett. Ha érdekli, olvassa el webfejlesztőnk történetét: .
Honnan kezdjük a fejlesztéseket és hogyan maradjunk életben
Ha a dokumentációja olyan terjedelmes, mint az ISPsystemé, és nem tudja, hol kezdje, a legkomolyabb problémákkal kezdje. Ha az ügyfelek nem értik a dokumentációt – foglalkozzon a szövegek javításával, készítsen normákat, képezze ki az írókat. Ha a dokumentáció elavult – foglalkozzon a belső folyamatokkal. Kezdje a legnépszerűbb cikkekkel a keresettebb termékekről: kérdezze meg a támogatást, nézze meg a weboldal analitikáját és a keresési lekérdezéseket.
Azonnal mondjuk – nem lesz könnyű. És valószínűleg gyors sem. Kivéve, ha most kezd és mindent az elejétől jól csinál. Egy dolog biztos – az idő múlásával jobb lesz. De a folyamat sosem ér véget :-).
Forrás: habr.com
