Vývojári Prečo by ste nemali prekročiť dokumentáciu

Vo vývojovej oblasti mobilných aplikácií, webových aplikácií, desktopových aplikácií alebo knižníc JavaScript dokumentácia hrá dôležitú úlohu, ktorá by mohla určiť úspech vývoja softvéru. Ale ak ste niekedy urobili dokumentáciu, súhlasíte so mnou, že je pre vývojárov to skôr tá najmenšia obľúbená vec.

Na rozdiel od kódu písania (čo je to, čo si podpísali vývojári), dokumentácia (ktorú sme nemali) musí a mala by byť ľahko stráviteľná každý. Z technického hľadiska musíme prekladať strojový jazyk (kód) do jazyka, ktorý je pre človeka zrozumiteľný, čo je tvrdší ako to znie.

Aj keď to môže byť skutočne zaťažujúce, písanie dokumentácie je dôležité a prinesie výhody vašim používateľom, vašim kolegom a hlavne sebe.

Dobrá dokumentácia pomáha používateľom

Dokumentácia pomáha čitateľovi pochopiť, ako funguje kód, samozrejme. Mnohí vývojári však robia chybu predpokladať, že používatelia softvéru budú zdatní. Preto môže byť dokumentácia tenký materiál, preskočiť veľa základov, ktoré mal obsahovať od začiatku. Ak ste v jazyku dôvtipní, môžete z vlastnej iniciatívy vyriešiť veci; ak nie, potom ste stratený.

Dokumentácia určená pre používateľov zvyčajne pozostáva z praktického použitia alebo “ako”. Základné pravidlo pri vytváraní dokumentácie pre bežných používateľov je to mala by byť jasná. Použitie slov priateľských pre človeka je lepšie ako technické pojmy alebo žargón. Príklady reálneho používania budú tiež veľmi ocenené.

Dobrý dizajn rozloženia by tiež naozaj pomohol používateľom skenovať každú časť dokumentácie bez očného napätia. Niekoľko dobrých príkladov (aka moje obľúbené položky) je dokumentácia pre Bootstrap a WordPress ' “Prvé kroky s WordPress”.

Pomáha aj ďalším vývojárom

Každý vývojár bude mať svoj vlastný štýl kódovania. Ale pokiaľ ide o prácu v tíme, budeme často musieť zdieľať kódy s ostatnými spoluhráčmi. Takže je nevyhnutné mať konsenzus o štandarde aby sa všetci uchovali na tej istej stránke. Správne napísaná dokumentácia by bola odkazom, ktorý tím potrebuje

Na rozdiel od dokumentácie koncového používateľa však táto dokumentácia obvykle popisuje technických postupov ako konvencia pomenovania kódov, ktorá ukazuje, ako by mali byť vytvorené jednotlivé stránky, a ako API pracuje spolu s príkladmi kódu. Často by sme museli písať dokumentáciu v súlade s kódom (známym ako komentáre) s cieľom popísať, čo tento kód vykonáva.

Okrem toho v prípade, že máte nových členov Váš tím neskôr môže byť táto dokumentácia časovo efektívnym spôsobom, ako ich vycvičiť, takže nemusíte im dať 1-na-1 spustiť na kóde.

Zvláštne to tiež pomáha kódovač

Zaujímavá vec týkajúca sa kódovania je niekedy dokonca samotní vývojári nepochopili kód, ktorý napísali. Platí to najmä v prípadoch, keď boli kódy ponechané nedotknuté mesiace alebo dokonca roky.

Náhla potreba vrátiť kódy z jedného alebo druhého dôvodu by zanechala človeka, ktorý by sa pýtal, čo sa deje v ich mysli pri písaní týchto kódov. Nenechajte sa prekvapiť: už som v tejto situácii. Toto je presne keď som prial Správne som zdokumentoval môj kód.

Dokumentovaním kódov sa budete môcť rýchlo a bez frustrácie dostať na spodok vašich kódov a ušetriť tak veľa času, ktorý môžete využiť na získanie zmien.

Čo robí za dobrú dokumentáciu?

Existuje niekoľko faktorov, ktoré môžu stavať dobrú dokumentáciu.

1. Nikdy predpokladať

Nepredpokladajte, že vaši používatelia vedia čo vy vedieť aj čo oni chcieť vedieť. Je to vždy lepšie začať od samého začiatku bez ohľadu na úroveň znalostí používateľa.

Ak ste napríklad vytvorili doplnok jQuery, môžete sa inšpirovať dokumentáciou SlickJS. Ukazuje, ako štruktúrovať HTML, kde umiestniť CSS a JavaScript, ako inicializovať plugin jQuery na jeho najzákladnejšej úrovni a dokonca zobrazuje kompletnú konečnú značku po pridaní všetkých týchto vecí, čo je niečo zjavné.

Spodná časť je dokumentácia napísaná s myšlienkovým procesom používateľa, nie s vývojárom. Priblíženie vlastnej dokumentácie týmto spôsobom vám prinesie lepšiu perspektívu pri organizovaní vlastného diela.

2. Postupujte podľa štandardu

Pri pridávaní dokumentácie, ktorá je v súlade s kódom, použite štandard očakávaný od jazyka. Je vždy dobré popísať každú funkciu, premenné, ako aj hodnotu vrátenú funkciou. Tu je príklad dobrej inline dokumentácie pre PHP.

 / ** * Pridáva vlastné triedy do poľa tiel. * * @param array classes classes Triedy pre prvok tela. * @return array * / funkcia body_classes ($ classes) // Pridá triedu blogu na blogy s viac ako 1 publikovaným autorom. ak (is_multi_author ()) $ classes [] = 'group-blog';  návrat triedy $;  add_filter ('body_class', 'body_classes'); 

Nasledujú niekoľko odkazov na formátovanie inline dokumentácie s osvedčenými postupmi v PHP, JavaScript a CSS:

• PHP: PHP Documentation Standard pre WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Ak používate SublimeText, navrhujem, aby som nainštaloval DocBlockr, ktorý predstihne váš kód s inline dokumentáciou.

3. Grafické prvky

Použite grafické prvky, hovoria lepšie ako text. Tieto médiá sú užitočné, najmä ak vytvárate softvér s grafickým rozhraním. Môžete pridávať polohovacie prvky ako šípky, kružnice alebo čokoľvek, čo môže pomôcť používateľom zistiť, kam chodiť, bez toho, aby ste vedeli hádať.

Nasleduje príklad z aplikácie Tower, z ktorej môžete inšpirovať. Účinne vysvetľujú, ako funguje verzia ovládania verziou príjemným spôsobom, ktorý je viac pochopiteľný ako používanie riadkových riadkov na obyčajný text.

4. Sekcia

Môžete zvážiť zabalenie niekoľkých vecí v dokumentácii v odbočkách a tabuľkách, pretože to uľahčuje skenovanie a čítanie dlhšieho obsahu pre používateľov.

Pridajte tabuľku s obsahom a rozdelte dokumentáciu do ľahko stráviteľných sekcií, a pritom nechajte každú sekciu relevantnú s tým, čo príde ďalej. Udržujte ju krátku a priamočiaru. Nižšie je uvedený príklad pekne organizovanej dokumentácie na Facebooku. Obsah nás vedie, kam chceme skočiť.

5. Revízia a aktualizácia

Nakoniec prečítajte dokumentáciu o chybách a podľa potreby upravte, a kedykoľvek dôjde k významným zmenám v produkte, softvéri alebo knižnici. Vaša dokumentácia by nikomu nepomohla, ak nie je pravidelne aktualizovaná vedľa vášho produktu.