A szoftverdokumentáció csak cikkek halmaza. De még ők is megőrjíthetnek. Először is sokáig keresi a szükséges utasításokat. Akkor megérted a homályos szöveget. A leírtak szerint csinálod, de a probléma nem oldódott meg. Keresel egy másik cikket, ideges leszel... Egy órával később mindent feladod és távozol. Így működik a rossz dokumentáció. Mitől ilyen és hogyan javítható - olvasható a vágás alatt.
Régi dokumentációnkban sok hiányosság volt. Már közel egy éve dolgozunk rajta, hogy a fent leírt forgatókönyv ne érintse ügyfeleinket. Néz, и .
1. probléma: Nem világos, rosszul megírt cikkek
Ha a dokumentációt nem lehet megérteni, mi értelme van ennek? De érthetetlen cikkeket senki nem ír szándékosan. Ezek akkor történnek, amikor a szerző nem gondol a közönségre és a célra, vizet önt, és nem ellenőrzi a szövegben a hibákat.
- A közönség. Mielőtt cikket írna, gondolnia kell az olvasó felkészültségi szintjére. Logikus, hogy egy kezdőknek szóló cikkben nem szabad kihagyni az alapvető lépéseket, és a szakkifejezéseket hagyni magyarázat nélkül, de egy olyan ritka funkcióról szóló cikkben, amelyre csak a szakembereknek van szüksége, érdemes elmagyarázni a PHP szó jelentését.
- Gól. Még egy dolog, amit előre át kell gondolni. A szerzőnek világos célt kell kitűznie, meg kell határoznia a cikk hasznos hatását, és el kell döntenie, mit fog tenni az olvasó az elolvasása után. Ha ez nem történik meg, akkor a leírás kedvéért leírást kap.
- Víz és bogarak. Rengeteg a felesleges információ és bürokrácia, a hibák, elírások zavarják az észlelést. Még ha az olvasó nem is nyelvtani náci, a szövegben előforduló hanyagság kikapcsolhatja.
Vegye figyelembe a fenti tippeket, és a cikkek világosabbak lesznek - garantált. Hogy még jobb legyen, használja a mi .
2. probléma. A cikkek nem válaszolnak minden kérdésre
Rossz, ha a dokumentáció nem követi a fejlődést, nem válaszol valódi kérdésekre, és a benne lévő hibákat évekig nem javítják ki. Ezek nem annyira a szerző problémái, hanem a vállalaton belüli folyamatok szerveződése.
A dokumentáció nem követi a fejlődést
A funkció már kiadásban van, a marketing tervezi, hogy lefedje, majd kiderül, hogy az új cikk vagy fordítás még mindig nincs a dokumentációban. Emiatt még a megjelenést is el kellett halasztanunk. Megkérhet mindenkit, hogy amennyit akar, időben adja át a feladatokat a műszaki íróknak, de ez nem fog menni. Ha a folyamat nem automatizált, a helyzet megismétlődik.
Változtattunk a YouTrack-en. Az új szolgáltatásról szóló cikk megírása a műszaki íróra hárul abban a pillanatban, amikor megkezdődik a funkció tesztelése. Ezután a marketing tanul róla, hogy felkészüljön a promócióra. Az értesítések a Mattermost vállalati messengerben is érkeznek, így egyszerűen lehetetlen lemaradni a fejlesztők híreiről.
A dokumentáció nem tükrözi a felhasználói kéréseket
Megszoktuk, hogy így dolgozunk: kijött egy funkció, megbeszéltük. Leírtuk, hogyan kell be- és kikapcsolni, és hogyan kell finoman beállítani. De mi van akkor, ha egy ügyfél olyan módon használja a szoftverünket, ahogyan nem számítottuk rá? Vagy vannak olyan hibák, amelyekre nem gondoltunk?
Annak érdekében, hogy a dokumentáció a lehető legteljesebb legyen, javasoljuk, hogy elemezze a támogatási kérelmeket, a tematikus fórumokon feltett kérdéseket és a keresőmotorokban történő lekérdezéseket. A legnépszerűbb témák átkerülnek a műszaki írókhoz, hogy kiegészítsék a meglévő cikkeket, vagy újakat írhassanak.
A dokumentációt nem javítják
Nehéz azonnal tökéletesen megcsinálni, még mindig lesznek hibák. Lehet reménykedni a vásárlók visszajelzésében, de nem valószínű, hogy minden elírást, pontatlanságot, érthetetlen vagy alaptalan cikket jelezni fognak. Az ügyfelek mellett az alkalmazottak is elolvassák a dokumentációt, ami azt jelenti, hogy ugyanazokat a hibákat látják. Ezt lehet használni! Csak olyan feltételeket kell teremtenie, amelyek között könnyű lesz jelenteni a problémát.
Van egy csoportunk a belső portálon, ahol az alkalmazottak megjegyzéseket, javaslatokat és ötleteket írnak le a dokumentációval kapcsolatban. Kell a támogatásnak egy cikk, de az nem létezik? Észrevette a tesztelő a pontatlanságot? A partner panaszt tett a fejlesztési vezetőknek hibák miatt? Mind ebben a csoportban! A műszaki írók néhány dolgot azonnal kijavítanak, bizonyos dolgokat áthelyeznek a YouTrack szolgáltatásba, másoknak pedig gondolkodási időt adnak. A téma elhalványulásának elkerülése érdekében időnként emlékeztetünk a csoport létezésére és a visszajelzések fontosságára.
3. probléma. Sok időt vesz igénybe a megfelelő cikk megtalálása.
A nem található cikk semmivel sem jobb, mint a nem található cikk. A jó dokumentáció mottója legyen „Könnyen kereshető, könnyen megtalálható”. Hogyan lehet ezt elérni?
Szervezd meg a szerkezetet és határozd meg a témaválasztás elvét. A szerkezetnek a lehető legátláthatóbbnak kell lennie, hogy az olvasó ne gondolja azt, hogy „Hol találom ezt a cikket?” Összefoglalva, két megközelítés létezik: a felületről és a feladatokból.
- A felületről. A tartalom megkettőzi a panelszakaszokat. Ez volt a helyzet a régi ISP-rendszer dokumentációjában.
- Feladatokból. A cikkek és rovatok címei a felhasználók feladatait tükrözik; A címek szinte mindig tartalmaznak igéket és a „hogyan kell” kérdésre adott válaszokat. Most áttérünk erre a formátumra.
Bármelyik megközelítést is választja, győződjön meg arról, hogy a téma releváns a felhasználók által keresett dolgok szempontjából, és olyan módon kerül lefedésre, amely kifejezetten a felhasználó kérdésére vonatkozik.
Állítson be központi keresést. Egy ideális világban a keresésnek akkor is működnie kell, ha elgépeli vagy hibázik a nyelv. Az eddigi Confluence-i keresésünk ezzel nem tudott örömet okozni. Ha sok terméke van, és a dokumentáció általános, szabja a keresést arra az oldalra, amelyen a felhasználó tartózkodik. Esetünkben minden terméknél működik a főoldali keresés, ha pedig már egy adott rovatban vagy, akkor csak az abban szereplő cikkeknél.
Adjon hozzá tartalmat és kenyérmorzsát. Jó, ha minden oldal rendelkezik menüvel és navigációs útvonallal – a felhasználó elérési útja az aktuális oldalra, és bármilyen szintre visszatérhet. A régi ISPsystem dokumentációban a tartalom eléréséhez ki kellett lépnie a cikkből. Kellemetlen volt, ezért javítottuk az újban.
Helyezzen linkeket a termékbe. Ha az emberek újra és újra ugyanazzal a kérdéssel fordulnak támogatáshoz, célszerű egy tippet hozzáadni a megoldáshoz a felülethez. Ha adatokkal vagy betekintéssel rendelkezik arról, hogy a felhasználó mikor tapasztal problémát, levelezőlistával is értesítheti őket. Mutasd meg nekik aggodalmukat, és vedd le a terhet a támogatásról.
A felugró ablak jobb oldalán található egy hivatkozás a DNSSEC beállításáról az ISPmanager tartománykezelés szakaszában.
Állítson be kereszthivatkozásokat a dokumentációban. Az egymáshoz kapcsolódó cikkeket „linkelni” kell. Ha a cikkek szekvenciálisak, ügyeljen arra, hogy minden szöveg végéhez adjon előre és hátra nyilakat.
Valószínűleg egy személy először nem neked, hanem egy keresőmotornak keresi a választ a kérdésére. Kár, ha technikai okokból nincs link a dokumentációhoz. Tehát ügyeljen a keresőoptimalizálásra.
4. probléma. Az elavult elrendezés zavarja az észlelést
A rossz szövegek mellett a dokumentációt a tervezés is elronthatja. Az emberek hozzászoktak a jól megírt anyagok olvasásához. Blogok, közösségi hálózatok, média – minden tartalom nemcsak szép, hanem könnyen olvasható és kellemes a szemnek. Ezért könnyen megértheti annak a személynek a fájdalmát, aki olyan szöveget lát, mint az alábbi képernyőképen.
Annyi képernyőkép és kiemelés található ebben a cikkben, hogy nem segítenek, csak zavarják az észlelést (a kép kattintható)
Nem szabad hosszasan olvasni a dokumentációból egy csomó effektussal, de figyelembe kell venni az alapvető szabályokat.
Elrendezés. Határozza meg a törzsszöveg szélességét, betűtípusát, méretét, címsorait és kitöltését. Béreljen fel egy tervezőt, és a munka elfogadásához vagy saját maga elkészítéséhez olvassa el Artyom Gorbunov „Tipográfia és elrendezés” című könyvét. Csak egy nézetet mutat az elrendezésről, de ez is elég.
Kiosztások. Határozza meg, hogy a szövegben mi igényel hangsúlyt. Jellemzően ez egy elérési út a felületen, gombokon, kódbeillesztéseken, konfigurációs fájlokon, „Kérem, vegye figyelembe” blokkokban. Határozza meg, hogy ezeknek az elemeknek milyen allokációi lesznek, és rögzítse azokat a szabályzatban. Ne feledje, hogy minél kevesebb a váladékozás, annál jobb. Ha sok van belőlük, a szöveg zajos. Még az idézőjelek is zajt keltenek, ha túl gyakran használják őket.
Pillanatképek. Egyezzen meg a csapattal, hogy milyen esetekben van szükség képernyőképekre. Egyáltalán nem kell minden lépést szemléltetni. Nagyszámú képernyőkép, pl. külön gombok, zavarják az érzékelést, elrontják az elrendezést. Határozza meg a képernyőképeken található kiemelések és aláírások méretét, formátumát, és rögzítse a szabályzatban. Ne feledje, hogy az illusztrációknak mindig meg kell felelniük a leírtaknak, és relevánsaknak kell lenniük. Ismétlem, ha a terméket rendszeresen frissítik, nehéz lesz mindenkit nyomon követni.
Szöveg hossza. Kerülje a túl hosszú cikkeket. Bontsd részekre, és ha ez nem lehetséges, adj hozzá tartalmat horgonylinkekkel a cikk elejéhez. Egy cikk vizuálisan rövidebbé tételének egyszerű módja, ha egy szűk olvasói kör számára szükséges technikai részleteket spoiler alá rejtjük.
formátumok. Kombináljon több formátumot a cikkekben: szöveget, videót és képeket. Ez javítja az érzékelést.
Ne próbálja gyönyörű elrendezéssel elfedni a problémákat. Őszintén szólva, mi magunk reméltük, hogy a „csomagoló” megmenti az elavult dokumentációt - ez nem sikerült. A szövegek annyi vizuális zajt és szükségtelen részletet tartalmaztak, hogy a szabályozás és az új dizájn tehetetlen volt.
A fentiek nagy részét a dokumentációhoz használt platform határozza meg. Például nálunk van Confluence. Vele is bíbelődnem kellett. Ha érdekel, olvassa el webfejlesztőnk történetét: .
Hol kezdjem el a fejlődést és hogyan éljük túl
Ha a dokumentációja olyan széles, mint az ISPsystemé, és nem tudja, hol kezdje, kezdje a legnagyobb problémákkal. Az ügyfelek nem értik a dokumentumot - javítsák a szövegeket, alkossanak rendeleteket, képezzék ki az írókat. A dokumentáció elavult - ügyeljen a belső folyamatokra. Kezdje a legnépszerűbb cikkekkel a legnépszerűbb termékekről: kérjen támogatást, nézze meg a webhelyelemzéseket és a keresőmotorok lekérdezéseit.
Mondjuk rögtön – nem lesz könnyű. És az sem valószínű, hogy gyorsan működik. Kivéve, ha csak most kezdi, és nem cselekszik azonnal a megfelelő módon. Egy dolgot biztosan tudunk, hogy idővel jobb lesz. De a folyamatnak sosem lesz vége :-).
Forrás: will.com