Milyen stílusú dokumentációt kell használniuk a termékmenedzsereknek, hogy a megfelelő üzenetet közvetítsék?

A dokumentáció minden nyílt forráskódú projekt egyik legfontosabb és legkevésbé értékelt eleme, és nem szabad félvállról venni.

Általánosságban elmondható, hogy a legtöbb nyílt forráskódú projekt egyszerűen azért nem kap megfelelő figyelmet, mert a szerzőik nem igazán érdekeltek, nem képesek vagy nincs idejük arra, hogy hatékony dokumentációs környezetet hozzanak létre az API- és termékdokumentációjukhoz.

Hiába kiváló az alkalmazás, ha a dokumentáció nem megfelelő, a fogyasztók nem fogják tudni hasznosítani a használatát.

Azonban még ha nincs is más lehetőségük, minthogy bármilyen okból kihasználják, akkor sem fogják tudni sikeresen vagy olyan módon használni, ahogyan Ön szeretné.

Annak megértése, hogyan kell kiváló dokumentációt készíteni, jelentős mennyiségű munkát igényel, ahogyan más dokumentációs projektek rendszeres felülvizsgálata is. De higgye el nekem - mint olyasvalakinek, aki rengeteg dokumentációt készített a Docsie számára -, ha olyan kódot készít, amelyet nem ön fog használni, és különösen, ha ezek az emberek az ön ügyfelei, akkor a termékének jól dokumentáltnak, formázottnak és dinamikusan megjelenítettnek kell lennie.

Mi a különbség az oktatóanyagok, a how-to's, a magyarázatok és a referenciák között?

Sokan tévesen azt hiszik, hogy a négy kifejezés ugyanazt a tárgyat jelöli. Valójában azonban számos különböző jelentést fejeznek ki. Ezek a különböző típusú dokumentációk igen lényeges és néhány alapvető különbséggel rendelkeznek:

Tutorials dokumentáció: Az ilyen típusú dokumentációk információalapú, képzésre orientált dokumentációk.

How-To útmutatók/felhasználói útmutatók dokumentáció: Használati útmutatók dokumentációk kifejezik, hogyan lehet egy adott problémát egy lépéssorozaton keresztül megoldani egy adott cél elérése érdekében.

Magyarázó dokumentáció: Ezek a cikk típusú dokumentációk, amelyek célja, hogy a felhasználó/olvasó különböző magyarázatok és háttér-információk segítségével mélyebben megértse a terméket.

Hivatkozási megjegyzések dokumentációja: Ez a dokumentáció arra szolgál, hogy tájékoztassa a felhasználót a különböző új funkciók frissítéseinek és felhasználásainak leírásáról. Ez a fajta dokumentáció nagyon "nyers" lehet fejlesztői dokumentáció formájában, azonban felhasználóbarátabb, a végfelhasználó számára könnyen érthető kiadási jegyzetekké is lefordíthatók.

A jó minőségű dokumentáció készítésének okai

Mielőtt továbblépnénk, fontos megértenünk, hogy a hozzáértő dokumentációkészítés miért nagyon fontos, mégis alulértékelt igény a mai társadalomban. A széles körű és jól megírt dokumentáció elérhetősége az egyik legfontosabb kritérium a széles körű elfogadás eléréséhez, különösen a nyílt forráskódú projektek esetében, ahol gyakorlatilag minden művelet elérhető a nyilvánosság számára, és ahol az ilyen tevékenységek döntő szerepet játszanak a projekt sikerében.

Nézzük meg a hatékony dokumentáció megírásának legfontosabb okait.

Lehetővé teszi, hogy jobb bevezetési élményt nyújtson az ügyfelek számára.

Ha megfelelő dokumentációt biztosít a termékéről az ügyfeleinek, azzal segíti őket, hogy jobban érzik magukat a termékével kapcsolatban, és védettebbnek érzik magukat a termék speciális irányelvei által. Ehhez a következőket kell tennie:

1. Biztosítsa, hogy a termékdokumentációja látható és könnyen hozzáférhető legyen, akár alkalmazáson belüli linkeken keresztül, akár egy kereshető dokumentációs platform alatt.

2. Biztosítsa, hogy jól megírtak legyenek, és segítsék az ügyfelet abban, hogy gyorsan és könnyen megtalálja a választ.

Az egyik tanács, hogy csak egyszer írja meg a dokumentációját, és azt újra és újra megemésztik, amikor új ügyfelek érkeznek a vállalatához.

Ennek következtében kevesebb lesz a támogatási megkeresés.

Azok az ügyfelek, akik elolvassák és megértik a dokumentációját, nagyobb valószínűséggel vásárolják meg az Ön termékeit. Ha az ügyfelek nem tudnak rájönni valamire, az eléggé bosszantó lehet, és elkezdhetik inkább az Ön termékét hibáztatni.

Egyes ügyfelek azonnal kapcsolatba lépnek a támogató munkatársakkal vagy e-mailt küldenek nekik, ha valami bökkenőbe ütköznek; de ha a dokumentáció vonzó, könnyen hozzáférhető és érthető, akkor képesek lesznek saját maguk megoldani a problémáikat anélkül, hogy Önnel kellene konzultálniuk, ami viszont azt eredményezi, hogy nagyobb felhatalmazást éreznek.

Segít támogatni a saját csapatát.

Egy robusztus tudásbázis a saját csapattagok támogatására is használható. Így a belső csapatodat tájékoztatni kell az új funkciókról, a tervezett ütemtervekről, az API dokumentációról és minden másról, ami ahhoz szükséges, hogy mindenki egy oldalon álljon.

Lépésről lépésre útmutató a hatékony dokumentáció megírásához

A dokumentum tartalmának megírása és e tevékenység megszervezése két teljesen más feladat, mint annak meghatározása, hogy milyen hangnemet használjon, és hogyan biztosítsa, hogy a dokumentációja érthető legyen. Ahogyan O'Reilly, a kiváló dokumentációnak 8 szabálya van állítja:

1. Készítsünk olyan dokumentációt, amely hívogató az olvasó számára.

2. Készítsen alapos dokumentációt, amely a projekt minden területére kiterjed.

3. Hozzanak létre könnyen érthető, áttekinthető anyagot.

4. Készítsen olyan dokumentációt, amely esettanulmányokon keresztül mutatja be a termék használatát.

5. Írjon olyan dokumentációt, amely szükség esetén ismétléseket tartalmaz.

6. Írjon olyan dokumentációt, amely naprakész.

7. Írjon olyan dokumentációt, amelyhez egyszerű hozzájárulni

8. Írjon olyan dokumentációt, amelyet könnyű felfedezni és megérteni

Ezek az elemek leginkább a tartalommal kapcsolatosak. Ezt követően hat lépésben foglalkozunk az információ strukturálásának "hogyanjával":

Döntsd el, hogy mit kell rögzítened.

Szánjon egy kis időt arra, hogy átgondolja, milyen dokumentációt fog készíteni, mielőtt elkezdi: oktatóanyag, referenciadokumentum, használati utasítás vagy magyarázat lesz?

Vegye figyelembe, hogy a termék jellege közvetlen hatással lesz arra, hogy milyen dokumentáció elkészítéséért lesz felelős.

Hozzon létre egy keretrendszert.

Először építsen alapot a dokumentációjának. Ez kezdetben lehet valami nagyon aprócska dolog, és mindössze néhány csoportból állhat, de idővel az egész platform, amelyre építkezik, elkezd méretben és összetettségben növekedni. Rendszeresen felül kell vizsgálnia a szervezeti felépítését.

Tartsa szem előtt, hogy Ön az oktató, és végső soron Ön felelős azért, hogy a tanítványai hogyan tanulnak az osztályában. Az Ön utasításai fogják őket irányítani; ezért minél több időt fordít a struktúrára, annál sikeresebbek lesznek a tanítványai a törekvéseikben.

Mindig használja ki az egészséges multimédiás technikákat.

Győződjön meg róla, hogy videókat, rajzokat és változatos stílusokat használ, és közvetlenül a dokumentációjába kapcsolja be őket. A Docsie lehetővé teszi ezek bármelyikének beágyazását a platformunkon belül, hogy megkönnyítse ezt a folyamatot.

Nemcsak abban segítenek a fogyasztóknak, hogy jobban megértsék az Ön által kifejezett információkat, hanem fantasztikus keresőoptimalizálást is biztosítanak, ami a dinamikus dokumentációjának eredményeként nagyobb számú, magas minőségű leadhez vezet.

Győződjön meg róla, hogy kereshető.

A különböző tudásbázis-platformok keresési képességei között különbségek vannak - egyesek csak alapszintű keresést kínálnak, amely nem teszi lehetővé a szegmentációkra való lefelé fúrást (ami technikailag rendben van, ha nincs több ezer fájlja), míg mások olyan lekérdezési lehetőségeket kínálnak, amelyek lehetővé teszik a keresést nemcsak a dokumentumokban, hanem a felhasználónevekben is.

Egy dolog azonban kritikus: olyan eszközt kell használnia, amely lehetővé teszi a gyors keresést. Az alkalmazásban található keresési funkcióval egyszerűen kereshet fájlokat, és előnézetet kaphat róluk anélkül, hogy elhagyná az alkalmazást.

A Docsie lehetővé teszi a dinamikusan kereshető navigációt a könnyen elérhető információkhoz.

Folyamatosan törekszik a fejlesztésre és frissítésre

A dokumentumok létrehozása és felhasználása nehéz, mert azok a személyek, akik létrehozták vagy hasznot húztak belőlük, gyorsan elfelejtik őket. A dokumentumok útjuk során számos kihívással is szembesülnek.

Az idő múlásával a mappastruktúra temetői jelleget ölt, mivel a régebbi dokumentáció hajlamos a monitor képernyőjén alacsonyabb pozícióban maradni.

Ezért mindenképpen nézze át újra a régi dokumentációját, és végezzen javításokat, valamint időről időre ösztönözze kollégáit is erre. A Docsie lehetővé teszi a frissítések létrehozását fejlett verziókezelő rendszerünkön keresztül, ami egyszerű és könnyen elvégezhető.

Végső gondolatok:

Szeretne többet megtudni arról, hogyan kell hatékony dokumentációt írni? A szoftverdokumentációval foglalkozó szakemberek számára rengeteg blogot és információt találnak itt.