Fejlesztők Miért nem hagyja ki a dokumentációt

A mobilalkalmazások, webalkalmazások, asztali alkalmazások vagy JavaScript könyvtárak fejlesztésének területén a dokumentáció fontos szerepet játszik, amely meghatározhatja a szoftver fejlődésének sikerét. De ha valaha is dokumentációt készítettél, egyetértesz velem, hogy a fejlesztők számára ez a legkevésbé kedvelt dolog.

Ellentétben az írási kóddal (amit a fejlesztők feliratkoztak), a dokumentációnak (amit nem tettünk) meg kell, és könnyen meg kell emelniük mindenki. Technikailag le kell fordítanunk egy gépi nyelvet (kódot) az emberek számára érthető nyelvre, ami keményebb, mint amilyennek hangzik.

Bár ez igazi terhet jelenthet, a dokumentáció írása fontos, és előnyöket biztosít a felhasználóknak, munkatársainak és különösen magának.

A jó dokumentáció segít a felhasználóknak

A dokumentáció segít az olvasónak megérteni, hogyan működik a kód, magától értetődően. De sok fejlesztő hibát követ el azzal a feltételezéssel, hogy a szoftver használói képesek lesznek. Ennélfogva a dokumentáció vékony anyag lehet, kihagyva egy csomó lényeget, amit az elejétől kezdve kellett volna tartalmaznia. Ha a nyelvben hozzáértés van, akkor a saját kezdeményezésére kiderítheti a dolgokat; ha nem, akkor elveszett.

A felhasználóknak szánt dokumentáció általában gyakorlati felhasználásból vagy a “hogyan kell”. A hüvelykujjszabály az általános felhasználók dokumentációjának létrehozásakor világosnak kell lennie. Az emberbarát szavak használata előnyösebb, mint a technikai kifejezések vagy a zsargon. A valós felhasználási példák is nagyra értékelik.

A jó elrendezés is segíthet a felhasználóknak a dokumentáció minden egyes részének szkennelés nélküli szkennelésében. Néhány jó példa (más néven a kedvencek) a Bootstrap és a WordPress dokumentációja. “Első lépések a WordPress segítségével”.

Segít más fejlesztőknek is

Minden fejlesztőnek saját kódolási stílusa lesz. De amikor egy csapatban dolgozunk, gyakran meg kell osztanunk a kódokat a többi csapattárssal. Tehát elengedhetetlen konszenzusra van szükségük hogy mindenki ugyanazon az oldalon maradjon. A csapat igényeinek megfelelően a megfelelő írásos dokumentáció lenne

A végfelhasználói dokumentációval ellentétben ez a dokumentáció általában leírja technikai eljárások mint a kódnevezési egyezmény, amely megmutatja, hogy az egyes oldalakat hogyan kell megépíteni, és az API hogyan működik együtt a kód példákkal. Gyakran be kell írnunk a dokumentációt a kóddal (az úgynevezett Hozzászólások), hogy leírja, mit csinál a kód.

Ezen kívül abban az esetben, ha van új tagok csatlakoznak a csapatod később, ez a dokumentáció időhatékony módja lehet, hogy kiképezhesse őket, így nem kell megadnod egy 1-től-1-ig a kódon.

Furcsa módon segít a kódolónak is

A kódolás vicces dolog az, hogy néha még a fejlesztők maguk sem értik az általuk írt kódot. Ez különösen igaz azokban az esetekben, amikor a kódokat hónapokig vagy akár évekig érintetlenül hagyották.

Hirtelen szükség van arra, hogy a kódokat egy vagy több okból újra megvizsgáljuk, és egy csodálkozásra hagyja, hogy mi történt a fejükben, amikor ezeket a kódokat írták. Ne lepődj meg: korábban voltam ebben a helyzetben. Ez pontosan amikor én kívánta A kódomat megfelelően dokumentáltam.

A kódok dokumentálásával gyorsan és frusztráció nélkül eljuthat a kódjainak aljához, és sok időt takaríthat meg, amivel eltöltheti a változtatásokat.

Mi teszi a jó dokumentációt?

Számos tényező van, hogy egy jó dokumentációt építsünk.

1. Soha Ne feltételezzük

Ne feltételezzük, hogy a felhasználók tudják, mit Ön tudni, és mi is ők akarom tudni. Mindig jobb kezdeni függetlenül a felhasználók jártassági szintjétől.

Ha például egy jQuery plugint épített, akkor inspirálhat a SlickJS dokumentációjából. Megmutatja, hogyan kell strukturálni a HTML-t, hogy hová tegye a CSS-t és a JavaScript-et, hogyan kell inicializálni a jQuery plugint a legalapvetőbb szintjén, és még a teljes végleges jelölést is megjeleníti, miután hozzáadtuk ezeket a dolgokat, ami valami nyilvánvaló.

Az alsó sorban a dokumentáció a felhasználó gondolkodási folyamatával van írva, nem pedig fejlesztő. A saját dokumentációjához közeledve jobb perspektíva lesz a saját darabod megszervezésében.

2. Kövesse a szabványt

A kóddal összekapcsolt dokumentáció hozzáadásával, használja a nyelvtől elvárt szabványt. Mindig jó ötlet leírni az egyes funkciókat, a változókat, valamint a függvény által visszaadott értéket. Itt van egy példa a PHP jó inline dokumentációjára.

 / ** * Egyéni osztályokat ad a testosztályokhoz. * * @param tömb $ osztályok A testelem osztályai. * @return array * / function body_classes ($ osztályok) // A csoportos blogosztályt hozzáadja a több mint 1 szerzőt tartalmazó blogokhoz. ha (is_multi_author ()) $ class [] = 'csoport-blog';  vissza $ class;  add_filter ('body_class', 'body_classes'); 

Az alábbiakban néhány hivatkozást olvashat a inline dokumentáció formázására a PHP, a JavaScript és a CSS legjobb gyakorlataival kapcsolatban:

• PHP: PHP dokumentációs szabvány a WordPress számára
• JavaScript: UseJSDoc
• CSS: CSSDoc

Ha SublimeText-et használ, azt javaslom, hogy telepítsd a DocBlockr-ot, amely ügyesen előzi meg a kódodat inline dokumentációval.

3. Grafikai elemek

Grafikus elemeket használ, jobban beszélnek, mint a szöveg. Ezek a médiák hasznosak, különösen akkor, ha grafikus felületű szoftvert építenek. Hozzáadhat olyan mutatóelemeket, mint a nyilak, kör vagy bármi, ami segíthet a felhasználóknak abban, hogy kitalálják, hová menjenek a lépések végrehajtásához, találgatás nélkül.

Az alábbiakban egy példa a Tower alkalmazásból, ahol ihletet nyerhet. Hatékonyan elmagyarázzák, hogy hogyan működik a verzióvezérlés kellemes módon, ami érthetőbbé teszi, mint a sima szöveges parancssorok használata.

4. Szekció

Lehet, hogy néhány dolgot belefoglalhat a dokumentációba a feltüntetett listákon és táblázatokon, mivel ez megkönnyíti a felhasználók számára a szkennelés és olvasás hosszabb tartalmát.

Adjon hozzá egy tartalmi táblázatot, és hasonlítsa össze a dokumentációt könnyen emészthető részekben, mégis tartsa az egyes részeket relevánsnak a következővel. Tartsa rövid és egyszerű. Az alábbiakban egy példa a szépen szervezett dokumentációra a Facebookon. A tartalomjegyzék azt mutatja meg, hogy hová szeretnénk ugrani egy kattintással.

5. Módosítsa és frissítse

Végül, tekintse át a dokumentációkat a hibákért, és szükség esetén módosítsa, illetve ha a termékben, a szoftverben vagy a könyvtárban jelentős változások következnek be. A dokumentáció nem lenne hasznos bárki számára, ha nem frissíti rendszeresen a terméket.