Ako písať softvérovú dokumentáciu: 8 krokov

Dobrá softvérová dokumentácia - či už ide o dokument, ktorý obsahuje špecifikáciu požiadaviek pre programátorov alebo testerov, technický dokument pre interných používateľov, príručka na používanie softvéru alebo programového výziev pre používateľov - pomáha osobe pracujúcemu so softvérom, pochopiť jeho charakteristické funkcie a funkcie. Postupujte podľa tipov - Ako písať softvérovú dokumentáciu pre technických a koncových užívateľov.

Kroky

Metóda 1 z 2:

Písanie softvérovej dokumentácie pre technických používateľov.

jeden. Určite, ktoré informácie sa musia uviesť. Dokumenty o požiadavkách na softvér slúžia ako referenčná príručka pre dizajnérov používateľského rozhrania, programátorov, ktorí píšu kód a testery, ktoré kontrolujú, či softvér funguje nasledovne. Presné informácie závisia od samotného programu, ale môže obsahovať nasledovné:

Kľúčové súbory v aplikácii. Môžu to byť súbory vytvorené vývojárskym tímom, databázy spôsobené počas prevádzky softvéru a programy služieb tretích strán.
Funkcie a podprogramy. Uvádza sa tu, že každá funkcia a podprogram vytvára, vrátane vstupných a výstupných hodnôt.
Softvérové premenné a konštantné a ako sa používajú v aplikácii.
Všeobecná štruktúra programu. Pri aplikáciách založených na disku budete pravdepodobne potrebovať popis jednotlivých blokov a programových knižníc, zatiaľ čo webové aplikácie budú potrebovať popis stránok, ktoré používajú súbory.

Obrázok s názvom Write Software Dokumentácia Krok 2

2. Rozhodnúť, koľko dokumentácie by mala byť v programovom kóde a koľko by sa malo oddeliť. Čím viac je technická dokumentácia vytvorená v programovom kóde, tým jednoduchšie aktualizuje tento kód ako dokumentáciu týkajúcu sa rôznych verzií pôvodnej aplikácie. Dokumentácia v programovom kóde by mala obsahovať funkcie, podprogramy, softvérové konštanty a premenné.

Ak je programový kód pomerne dlhý, môže byť umiestnený ako referenčný súbor, v ktorom môžete vyhľadávať podľa kľúčových slov alebo značiek. Bude to veľký plus pre aplikácie, kde je programová logika rozdelená na mnoho stránok a obsahuje pomocné čísla súborov, ako v určitých webových aplikáciách.

Niektoré programovacie jazyky, ako napríklad Java alebo NET Framework (vizuálna základná).Net, c #), majú svoje vlastné normy pre dokumentáciu kódu. V takýchto prípadoch postupujte podľa štandardných pokynov - koľko dokumentácie by mala byť zahrnutá do programového poriadku.

Obrázok s názvom Písanie softvérovej dokumentácie Krok 3

3. Vyberte si vhodný nástroj. Do určitej miery je to definované jazykom, na ktorom je kód napísaný, či už je to C ++, C #, Visual Basic, Java, alebo PHP - pre každý existuje náš vlastný nástroj. V ostatných prípadoch je použitý nástroj určený typom požadovanej dokumentácie.

Textový editor "Microsoft Word" -Cercing nástroj na vytvorenie samostatných dokumentácií textových súborov, ktoré bude jednoduché a stručné. Pre dlhé textové súbory, mnoho vývojárov technickej dokumentácie uprednostňuje výber programu Adobe FrameMaker.

Tipové súbory pre dokumentáciu kódu softvéru je možné napísať pomocou akéhokoľvek nástroja, napríklad Robohelp, Pomocník a manuálne, Doc-to-Help, MadCap Flare, alebo "Helplogix".

Metóda 2 z 2:

Písanie softvérovej dokumentácie pre koncových používateľov

jeden. Identifikujte komerčné úvahy pre vašu dokumentáciu. Hoci funkčné dôvody softvérovej dokumentácie pomáhajú používateľom pochopiť, ako používať aplikáciu, existujú aj iné dôvody, ako je pomoc pri podpore tovaru na trhu, zlepšenie obrazu spoločnosti a najdôležitejšiu vec, zníženie nákladov na technickú podporu. V určitých prípadoch je dokumentácia povinná dodržiavať určité pravidlá a právne požiadavky.

V žiadnom prípade by programová dokumentácia nemala nahradiť návrh zlého rozhrania. Ak si obrazovka aplikácie vyžaduje veľa vysvetľujúcej dokumentácie, je lepšie zmeniť dizajn na niečo viac intuitívne.

Obrázok s názvom Písanie softvérovej dokumentácie Krok 5

2. Pochopiť publikum, pre ktoré píšete dokumentáciu. Vo väčšine prípadov používatelia softvéru vedia len málo o počítačoch okrem aplikácií. Existuje niekoľko spôsobov, ako určiť, ako koordinovať svoje potreby s dokumentáciou.

Pozrite sa na profesie vo vlastníctve vašich potenciálnych používateľov. Správca systému je pravdepodobne odborníkom na používanie softvérových aplikácií, zatiaľ čo prevádzkovateľ zadávania údajov pravdepodobne vlastní aplikáciu, ktorú v súčasnosti používa pre zadávanie údajov.

Pozrite sa na samotných používateľov. Hoci ich pracovné miesta vo všeobecnosti určujú, čo sú ľudia zapojení, ale existujú významné rozdiely v tom, ako sa v tejto organizácii používajú určité pozície. Vedenie rozhovoru s potenciálnymi užívateľmi, môžete svoj názor pridať - robí názov príspevku povinnosti.

Pozri existujúcu dokumentáciu. Dokumentácia pre predchádzajúce verzie softvéru poskytuje približný koncept, ktorý používateľ potrebuje vedieť o používaní programu. Pamätajte však, že koncový užívatelia nemajú záujem o to, ako program funguje, je dôležité, aby vedeli, čo s tým môžu robiť.

Určite úlohy, ktoré sú potrebné pre túto prácu a aké úlohy sa musia vykonať pred vykonaním týchto úloh.

Obrázok s názvom Zápis softvérovej dokumentácie Krok 6

3. Určiť príslušný formát (y) dokumentácie. Softvérová dokumentácia môže byť štruktúrovaná v jednom z dvoch formátov - referenčná príručka a návod na použitie. Niekedy je lepšie vybrať zmiešanú verziu týchto dvoch formátov.

Referenčná príručka je určená na vysvetlenie nástrojov softvéru (tlačidlá, tabuľky, pole a dialógové okno) a ako tento nástroj nástrojov. Mnohé rýchle súbory sú napísané v tomto formáte a kontextové výzvy Pomocník zobrazí požadovanú tému po kliknutí na tlačidlo "Pomocník" na požadovanej obrazovke.

Návod na použitie Vysvetľuje, ako používať softvér na vykonanie konkrétnej úlohy. Inštrukcie používania má často vytlačený vodiaci alebo formát PDF, hoci niektoré výzvy zahŕňajú témy, ako vykonať konkrétnu úlohu. (Tieto referenčné témy zvyčajne nie sú kontextové, hoci môžu byť hypertextové odkazy) Inštrukcia použitia má často formu referenčnej knihy s popisom úlohy a pokyny krok za krokom.

Obrázok s názvom Písanie softvérovej dokumentácie Krok 7

4. Rozhodnúť, ktorý formát (formáty) dokumentácie by mali byť. Softvérová dokumentácia pre koncových užívateľov môže byť jeden alebo viac formátov: Print Guide, Dokumenty vo formáte PDF, súbory tipov alebo online pomoc. Každý z týchto formátov je vytvorený na zobrazenie používateľa, ako používať každú funkciu programu - či už je to stručný prehľad alebo sprievodca. Rovnako ako v prípade okamžitých súborov a online pomoci, dokumentácia môže mať demonštračné video alebo text s obrázkami.

Tipy a online pomocné súbory musia mať ukazovatele, vyhľadávanie podľa kľúčových slov, ktoré umožnia používateľovi rýchlo nájsť požadované informácie. Aj keď nástroje pre rýchle súbory môžu automaticky vytvoriť ukazovatele, je lepšie to urobiť manuálne pomocou podmienok, ktoré budú užívatelia s najväčšou pravdepodobnosťou vyhľadávať.

Obrázok s názvom Písanie softvérovej dokumentácie Krok 8

päť. Vyberte vhodný nástroj na vytvorenie dokumentácie. Tlačový sprievodcov alebo formát PDF je možné napísať v textových editoroch, ako napríklad "Word" alebo "FrameMaker", v závislosti od dĺžky a zložitosti príručky. Tipové súbory môžu byť napísané pomocou takýchto vývojových nástrojov, ako je "robohelp", "Pomoc a manuálne", "Doc-to-Help", "Flare", "Helplogix", alebo "HelpServer".

Tipy

Text by mal byť ľahko čitateľný, obrázky by sa mali nachádzať čo najbližšie k textu, ku ktorému patria. Posuňte dokumentáciu pre časti a logické témy. Každá časť alebo téma by sa mala týkať určitej otázky, či už je to jeden program alebo úloha. Súvisiace otázky by mali byť uvedené "sledovať aj" s hypertextovým odkazom, ak je to potrebné.
Všetky nástroje na vytvorenie dokumentácie, ktoré boli uvedené vyššie, môžu byť doplnené programom screenshots, ako je napríklad Snagit, ak dokumentácia vyžaduje určitý počet obrazoviek snímok. Rovnako ako v druhej dokumentácii, snímky obrazovky by mali vysvetliť, ako softvér funguje, a nie zavádzať používateľa.
Dôležité je aj tón písania dokumentácie, najmä ak je napísaný pre koncových užívateľov. Použite druhú tvár "vy" namiesto tretej strany "používateľov".

Čo potrebuješ

Nástroj na písanie dokumentácie / debubu
Nástroj na vytváranie screenshotov