Vývojáři Proč byste neměli přeskočit dokumentaci

V oblasti vývoje mobilních aplikací, webových aplikací, aplikací pro stolní počítače nebo knihoven JavaScript hraje dokumentace důležitou roli, která by mohla určit úspěšnost vývoje softwaru. Ale pokud jste někdy udělali dokumentaci, souhlasili byste se mnou, že je to pro většinu vývojářů takřka nejoblíbenější.

Na rozdíl od psaní kódu (což je to, co vývojáři podepsali), dokumentace (kterou jsme neměli) musí a měla by být snadno strávitelná pomocí každý. Technicky musíme překládat strojový jazyk (kód) do jazyka, který je lidem srozumitelný, což je tvrdší, než to zní.

I když to může být skutečná zátěž, psaní dokumentace je důležité a přinese výhody pro vaše uživatele, vaše kolegy a zejména sebe..

Dobrá dokumentace pomáhá uživatelům

Dokumentace pomáhá čtenáři pochopit, jak kód funguje, očividně. Mnozí vývojáři však dělají chybu za předpokladu, že uživatelé softwaru budou zběhlí. Dokumentace proto může být tenký materiál, přeskakující mnoho podstatných prvků, které měl od začátku obsahovat. Pokud jste v tomto jazyce důvtipný, můžete si to z vlastní iniciativy vymyslet; pokud nejste, pak jste ztraceni.

Dokumentace určená pro uživatele zpravidla spočívá v praktickém použití “jak”. Důležité pravidlo při vytváření dokumentace pro obecné uživatele je to mělo by být jasné. Použití slov přátelských k lidem je vhodnější než technické termíny nebo žargon. Také příklady z reálného použití budou velmi oceňovány.

Dobrý design rozvržení by také skutečně pomohl uživatelům skenovat každou část dokumentace bez namáhání očí. Několik dobrých příkladů (aka mým oblíbeným) je dokumentace pro Bootstrap a WordPress ' “První kroky s WordPress”.

Pomáhá ostatním vývojářům příliš

Každý vývojář bude mít vlastní kódovací styl. Ale pokud jde o práci v týmu, budeme často muset sdílet kódy s ostatními spoluhráči. Je tedy nezbytné mít shodu na standardu udržet všechny na stejné stránce. Řádně písemná dokumentace by byla referencí týmu

Na rozdíl od dokumentace koncového uživatele však tato dokumentace obvykle popisuje technické postupy podobně jako konvence pojmenování kódu, která ukazuje, jak by měly být jednotlivé stránky vytvořeny a jak rozhraní API funguje spolu s příklady kódu. Často bychom také museli napsat dokumentaci s kódem (známým jako připomínky) popsat, co kód dělá.

Kromě toho, v případě, že máte nových členů Tato dokumentace by mohla být časově efektivním způsobem, jak je vycvičit, takže jim nemusíte dát kód 1 na 1.

Kupodivu to také pomáhá kodér

Vtipná věc na kódování je někdy ani samotní vývojáři nepochopili kód, který napsali. To platí zejména v případech, kdy kódy zůstaly nedotčené po celé měsíce nebo dokonce roky.

Náhlá potřeba vrátit se k kódům z jednoho nebo druhého důvodu by zanechala otázku, co se děje v jejich myslích, když psali tyto kódy. Nebuďte překvapeni: už jsem byl v této situaci. Tohle je přesně když já si přál Své kódy jsem řádně zdokumentoval.

Dokumentací vašich kódů se budete moci rychle a bez frustrace dostat na dno svých kódů, což vám ušetří spoustu času, který můžete strávit na získávání změn..

Co dělá dobrou dokumentaci?

Existuje několik faktorů, které budují dobrou dokumentaci.

1. Nikdy nepředpokládejte

Nepředpokládejte, že uživatelé vědí co vy stejně jako co oni Chcete vědět. Je to vždy lepší začít od samého začátku bez ohledu na úroveň znalostí uživatelů.

Pokud jste například vytvořili plugin jQuery, můžete se inspirovat dokumentací SlickJS. Ukazuje, jak strukturovat HTML, kam umístit CSS a JavaScript, jak inicializovat jQuery plugin na jeho nejzákladnější úrovni, a dokonce zobrazuje kompletní finální označení po přidání všech těchto věcí, což je něco zřejmého.

Spodní řádek je dokumentace napsaná s myšlenkovým procesem uživatele, nikoli vývojáře. Tím, že se k této dokumentaci přiblížíte, získáte lepší perspektivu při organizaci vlastního dílu.

2. Postupujte podle standardu

Při přidávání dokumentace, která je vložena s kódem, používat standard očekávaný od jazyka. Vždy je dobré popsat každou funkci, proměnné a hodnotu vrácenou funkcí. Zde je příklad dobré inline dokumentace pro PHP.

 / ** * Přidá vlastní třídy do pole tříd těla. * * @param array $ classes Třídy pro element těla. * @return array * / function body_classes ($ classes) // Přidá třídu blogu do blogů s více než 1 publikovaným autorem. if (is_multi_author ()) $ classes [] = 'group-blog';  návrat $ tříd;  add_filter ('body_class', 'body_classes');

Níže uvádíme několik odkazů na formátování inline dokumentace s osvědčenými postupy v PHP, JavaScriptu a CSS:

PHP: Dokumentace PHP Standard pro WordPress
JavaScript: UseJSDoc
CSS: CSSDoc

Pokud používáte SublimeText, doporučuji nainstalovat DocBlockr, který bude šikovně předplňovat váš kód inline dokumentací.

3. Grafické prvky

Používejte grafické prvky, mluví lépe než text. Tato média jsou užitečná, zejména pokud vytváříte software s grafickým rozhraním. Můžete přidat polohovací prvky, jako jsou šipky, kružnice nebo cokoliv, co může pomoci uživatelům zjistit, kam jít, aby provedli kroky, bez dohadů.

Následuje příklad z aplikace Tower, ze které můžete čerpat inspiraci. Efektivně vysvětlují, jak funguje správa verzí příjemným způsobem, díky čemuž je srozumitelnější než použití příkazových řádků s prostým textem.

4. Dělení

Můžete zvážit zabalení několika věcí do dokumentace v rámci seznamů s odrážkami a tabulek, což usnadňuje skenování a čtení obsahu pro uživatele.

Přidejte obsah a rozdělte dokumentaci do snadno stravitelných sekcí, přičemž každá část bude relevantní podle toho, co bude následovat. Udržujte ji krátkou a přímočarou. Níže je uveden příklad pěkně organizované dokumentace na Facebooku. Obsah nás zavede tam, kde chceme přeskočit kliknutím.

5. Revize a aktualizace

Nakonec si prostudujte dokumentaci k chybám a v případě potřeby proveďte revizi a kdykoli dojde k významným změnám produktu, softwaru nebo knihovny. Vaše dokumentace by nebyla pro nikoho užitečná, pokud není pravidelně aktualizována společně s vaším produktem.