Dokumentace softwaru
Dokumentace softwaru je psána text to doprovází počítač software. To jeden vysvětlí to jak to operuje nebo jak používat to. Ve skutečnosti, termín dokumentace softwaru znamená jiné věci k jiným lidem. Tento článek popíše termín jak použitý největšími skupinami uživatelů.Toto je co většina programátorů znamená když používá termín dokumentace softwaru. Když vytvoří software, kód sám je nedostatečný. Tam muset být nějaký text spolu s tím popisovat různé stránky jeho zamýšlené operace. Tato dokumentace je obvykle vložena uvnitř zdrojového kódu sám tak to je snadno přístupné komukoli kdo může být překračovat to.
Toto psaní může být velmi technické a je hlavně použitý vymezit a vysvětlit to API' s, datové struktury a algoritmy. Například, vysvětlovat to proměnná m _ jméno odkazuje se na první a poslední jméno osoby. To je důležité pro dokumenty kódu být důkladný, ale ne tak mnohomluvný že to stane se obtížné udržovat je.
Často, nástroje takový jako Doxygen nebo javadoc může být zvyklý na auto-tvořit dokumenty kódu a mdash; to je oni vytáhnou poznámky ze zdrojového kódu a vytvoří referenční příručky v takových formách jako text nebo HTML souborech. Dokumenty kódu jsou často organizovány do odkazového průvodcovského stylu, dovolovat programátora k rychle vyhledat libovolnou funkci nebo třídu.
Mnoho programátorů opravdu jako myšlenka na auto-tvořit dokumentaci pro různé důvody. Například, protože to je extrahováno ze zdrojového kódu sám (například, přes poznámky), programátor může psát to zatímco se odkazuje na jeho kód, a moci používat stejné nástroje on vytvořil zdrojový kód, dělat dokumentaci.
Samozřejmě, stinná stránka je to jen programátoři mohou editovat tento druh dokumentace a to závisí na nich obnovit výstup (například, tím, že provozuje cron úkol aktualizovat dokumenty každonoční). Někteří by charakterizovali toto jak pro poněkud než ošidit.
Unlike kód dokumentuje, dokumenty uživatele jsou obvykle daleko rozvedené se zdrojovým kódem programu, a místo toho jednoduše popsat jak to je používáno.
V případě knihovny softwaru, dokumentech kódu a uživateli dokumenty mohly být účinně rovnocenné a být hodnota spojovat se, ale pro obecné užití toto není často pravdivé. Na druhé straně, Lisp stroj odrostl tradice ve kterém každý kus kódu měl oddaný dokumentační řetězec. V kombinaci se silnými vyhledávacími schopnostmi (založený na Unixu- jako vhodný příkaz), a online zdroje, Lispm uživatelé mohli vyhledat dokumentaci a vložit sdruženou funkci přímo do jejich vlastního kódu. Tato úroveň snadnosti používání je neslýchaná v putatively modernějších systémech.
V obvyklém případě, dokumentace uživatele popisuje každý rys programu a různých požadovaných kroků odvolat se na to. Dobrý uživatelský dokument může také jít jak daleko jak poskytnout důkladnou diagnostickou asistenci. To je velmi důležité pro dokumenty uživatele nebýt matoucí, a pro je být nahoru doposud. Dokumenty uživatele nemusí být organizovány v nějaké zvláštní cestě, ale to je velmi důležité pro je mít důkladný index. Hustota a jednoduchost jsou také velmi cenní. Dokumentace uživatele je zvažována představovat kontrakt specifikovat co software bude dělat a should být prostý rysů undocumented.
Unlike kód nebo dokumentace uživatele, dokumenty designu inklinují brát hodně více širokého pohledu. Poněkud než popsat jak věci jsou používány, tento druh dokumentace zaostří více na proč. Například, v dokumentu designu, programátor by vysvětlil logický výklad vzadu organizovat datovou strukturu ve zvláštní cestě nebo odkázaný seznam členské funkce zvláštního objektu a jak přidat nové ke kódu. To vysvětlí důvody proč daná třída je postavena ve zvláštní cestě, poukáže na vzory, a dokonce jde jak daleko jak k nápadům obrysu pro cesty to mohlo být děláno lépe, nebo plánuje jak zlepšit to pozdnější na. Žádný z tohoto je vhodný k dokumentům kódu nebo dokumentům uživatele, ale to je důležitý pro design.
Toto je zvláštní plemeno dokumentů designu. Jistým způsobem, architekturní dokumenty jsou třetí derivát od kódu (design dokumentuje jsoucí druhý derivát a kód dokumentuje bytí nejprve). Velmi málo v dokumentech architektury je typický pro kód sám. Tyto dokumenty nepopíšou jak programovat zvláštní rutinu, nebo dokonce proč ta zvláštní rutina existuje ve formě že to dělá, ale místo toho pouze vyloží všeobecné požadavky, které by motivovaly existenci takový rutina. Dobrý architekturní dokument je krátký na detailech ale tlustý na vysvětlení. To může navrhnout přístupy pro design nižší úrovně, ale opustit aktuální zkoumání studia obchodu k ostatním dokumentům.
Další chov doktorů designu je dokument srovnání. Toto by často vzalo formu whitepaper. To se zaměří na jednu specifickou stránku systému a navrhne střídavé přístupy. To mohlo být u uživatelského rozhraní, kódu, designu nebo dokonce architektonické úrovně. To navrhne co Je situace je, a popisovat jednoho nebo více alternativ, a vyčíslit pros a ošidí každý. Dobrý obchodní studijní dokument je náročný na výzkum, vyjádří jeho myšlenku jasně (bez spoléhat se těžce na otupělý žargon oslnit čtenáře), a nejvíce důležitě je nezaujatý. To by mělo upřímně a jasně vysvětlit ceny kterýmkoliv řešení to nabídne jak nejlepší. Cíl studia obchodu má věštit nejlepší řešení, poněkud než tlačit zvláštní hledisko. To je dokonale přijatelné činit žádný závěr, nebo uzavřít, že žádný z alternativ být dostatečně lépe než základní čára ospravedlnit změnu. To by mělo být osloveno jako vědecká snaha, ne jako marketingová technika.
Na druhé straně obchodních studijních doktorů, pro mnohé žádosti to je nutné mít některé promoční materiály povzbudit nedbalé pozorovatele utrácet více učení času o produktu. Tato forma dokumentace má tři účely:
- Rozrušit potenciálního uživatele o produktu a instill v nich touha pro stát se více zapletený s tím.
- Informovat je o čem přesně produkt dělá, tak že jejich očekávání jsou v řadě s čím oni budou přjímat.
- To vysvětluje pozici tohoto produktu s úctou k jiným alternativám.
Viz též: Design kontraktem