Ako písať softvérovú dokumentáciu?
Nasledujú pokyny, ako napísať softvérovú dokumentáciu pre technických používateľov a koncových používateľov.
Dobrá dokumentácia k softvéru, či už je to dokument so špecifikáciami pre programátorov a testery, technický dokument pre interných používateľov alebo softvérové príručky a súbory pomocníka pre koncových používateľov, pomáha osobe pracujúcej so softvérom porozumieť jeho funkciám a funkciám. Dobrá softvérová dokumentácia je konkrétna, stručná a relevantná a poskytuje všetky informácie dôležité pre osobu, ktorá softvér používa. Nasledujú pokyny, ako napísať softvérovú dokumentáciu pre technických používateľov a koncových používateľov.
Metóda 1 z 2: Písanie softvérovej dokumentácie pre technických používateľov
- 1Zistite, aké informácie je potrebné zahrnúť. Dokumenty k softvérovej špecifikácii slúžia ako referenčné príručky pre návrhárov používateľského rozhrania, programátorov, ktorí píšu kód, a testerov, ktorí overujú, či softvér funguje tak, ako má. Presné informácie závisia od príslušného programu, ale môžu zahŕňať niektoré z nasledujúcich:
- Kľúčové súbory v aplikácii. To môže zahŕňať súbory vytvorené vývojovým tímom, databázy prístupné počas prevádzky programu a obslužné programy tretích strán.
- Funkcie a podprogramy. To zahŕňa vysvetlenie toho, čo každá funkcia alebo podprogram robí, vrátane rozsahu vstupných a výstupných hodnôt.
- Programové premenné a konštanty a spôsob ich použitia v aplikácii.
- Celková štruktúra programu. V prípade diskovej aplikácie to môže znamenať popis jednotlivých modulov a knižníc programu, zatiaľ čo pre webovú aplikáciu to môže znamenať opis, ktoré stránky používajú ktoré súbory.
- 2Rozhodnite, aká časť dokumentácie by mala byť v programovom kóde a koľko by od neho malo byť oddelené. Čím viac technickej dokumentácie sa v úvode zdrojového kódu programu vyvinie, tým jednoduchšie bude aktualizácia a údržba kódu, ako aj dokumentovanie rôznych verzií pôvodnej aplikácie. Dokumentácia v zdrojovom kóde musí minimálne vysvetliť účel funkcií, podprogramov, premenných a konštánt.
- Ak je zdrojový kód obzvlášť dlhý, môže byť zdokumentovaný vo forme súboru pomocníka, ktorý je možné indexovať alebo vyhľadávať pomocou kľúčových slov. Toto je osobitná výhoda pre aplikácie, kde je logika programu fragmentovaná na mnohých stránkach a obsahuje množstvo doplnkových súborov, ako je to pri určitých webových aplikáciách.
- Niektoré programovacie jazyky, ako napríklad Java a. NET Framework (Visual Basic.NET, C #) majú svoje vlastné štandardy na dokumentovanie kódu. V týchto prípadoch sa riaďte štandardmi, koľko dokumentácie by malo byť súčasťou zdrojového kódu.
Softvérová dokumentácia pre koncových používateľov môže mať jednu alebo niekoľko z mnohých foriem: vytlačené príručky, dokumenty PDF, súbory pomocníka alebo online pomoc. - 3Vyberte príslušný dokumentačný nástroj. Do určitej miery je to určené jazykom, v ktorom je kód napísaný, či už je to C ++, C#, Visual Basic, Java alebo PHP, pretože pre tieto a ďalšie jazyky existujú špecifické nástroje. V ostatných prípadoch je nástroj, ktorý sa má použiť, určený typom požadovanej dokumentácie.
- Programy na spracovanie textu pre program Microsoft Word sú dostatočné na vytváranie oddelených textových súborov dokumentácie, pokiaľ je dokumentácia pomerne krátka a jednoduchá. V prípade dlhých a zložitých textových súborov mnoho technických autorov uprednostňuje dokumentačný nástroj, akým je napríklad Adobe FrameMaker.
- Súbory pomoci pre dokumentovanie zdrojového kódu je možné vytvoriť pomocou ľubovoľného nástroja na tvorbu pomocníka, ako sú RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare alebo HelpLogix.
Metóda 2 z 2: Písanie softvérovej dokumentácie pre koncových používateľov
- 1Zistite obchodné dôvody svojej dokumentácie. Napriek tomu, že funkčným dôvodom zdokumentovania softvéru je pomôcť používateľom porozumieť používaniu aplikácie, existujú aj ďalšie dôvody, ako napríklad pomoc pri marketingu softvéru, zlepšenie imidžu spoločnosti a predovšetkým zníženie nákladov na technickú podporu. V niektorých prípadoch je dokumentácia potrebná na splnenie určitých predpisov alebo iných zákonných požiadaviek.
- V žiadnom prípade by však softvérová dokumentácia nemala nahradiť zlý dizajn rozhrania. Ak obrazovka aplikácie vyžaduje na jej vysvetlenie množstvo dokumentácie, je lepšie zmeniť vzhľad obrazovky na niečo intuitívnejšie.
- 2Pochopte publikum, pre ktoré píšete dokumentáciu. Vo väčšine prípadov majú používatelia softvéru malé znalosti o počítačoch mimo úloh, ktoré im umožňujú aplikácie, ktoré používajú. Existuje niekoľko spôsobov, ako zistiť, ako sa pomocou dokumentácie zaoberať ich potrebami.
- Pozrite sa na pracovné pozície, ktoré majú vaši potenciálni používatelia. Správca systému, je pravdepodobné, že odborník s radom softvérových aplikácií, zatiaľ čo zadávanie dát úradník je väčšia pravdepodobnosť, že viem len použitie on alebo ona v súčasnosti používa na zadanie dát.
- Pozrite sa na samotných používateľov. Napriek tomu, že názvy pracovných miest vo všeobecnosti naznačujú, čo ľudia robia, v spôsobe používania určitých názvov v rámci danej organizácie môžu existovať značné rozdiely. Pohovorom s potenciálnymi používateľmi môžete získať pocit, či sú vaše dojmy z toho, čo naznačuje názov ich práce, správne alebo nie.
- Pozrite sa na existujúcu dokumentáciu. Dokumentácia k predchádzajúcim verziám softvéru a funkčné špecifikácie poskytujú určité informácie o tom, čo bude používateľ potrebovať na používanie programu. Nezabúdajte však, že koncoví používatelia sa nezaujímajú o to, ako program funguje, ale o to, čo pre nich môže urobiť.
- Identifikujte úlohy potrebné na vykonanie práce a aké úlohy je potrebné vykonať, aby bolo možné tieto úlohy vykonať.
Dobrá softvérová dokumentácia je konkrétna, stručná a relevantná a poskytuje všetky informácie dôležité pre osobu, ktorá softvér používa. - 3Určte vhodný formát (-y) dokumentácie. Softvérová dokumentácia môže byť štruktúrovaná do 1 z 2 formátov, referenčnej príručky a používateľskej príručky. Niekedy je najlepším prístupom kombinácia formátov.
- Formát referenčnej príručky je venovaný vysvetleniu jednotlivých funkcií softvérovej aplikácie (tlačidlo, karta, pole a dialógové okno) a ich fungovaniu. V tomto formáte je napísaných veľa pomocných súborov, najmä kontextová pomoc, ktorá zobrazí relevantnú tému vždy, keď používateľ klikne na tlačidlo Pomocník na konkrétnej obrazovke.
- Formát užívateľská príručka vysvetľuje, ako používať softvér na vykonanie určitej úlohy. Používateľské príručky sú často formátované ako tlačené príručky alebo súbory PDF, aj keď niektoré súbory pomocníka obsahujú témy o tom, ako vykonávať konkrétne úlohy. (Tieto témy pomocníka zvyčajne nie sú kontextové, aj keď na ne možno hypertextovo odkazovať.) Príručky používateľa majú často formu návodov so zhrnutím úloh, ktoré je potrebné vykonať v úvode, a pokynmi uvedenými v očíslovaných krokoch..
- 4Rozhodnite, akú formu (-y) by mala mať dokumentácia. Softvérová dokumentácia pre koncových používateľov môže mať jednu alebo niekoľko z mnohých foriem: vytlačené príručky, dokumenty PDF, súbory pomocníka alebo online pomoc. Každý formulár je navrhnutý tak, aby ukázal používateľovi, ako používať každú z funkcií programu, či už vo forme návodu alebo tutoriálu; v prípade súborov pomocníka a online pomoci to môže zahŕňať ukážkové videá, ako aj text a statickú grafiku.
- Súbory pomocníka a online pomoc by mali byť indexované a vyhľadávané podľa kľúčových slov, aby používatelia mohli rýchlo nájsť informácie, ktoré hľadajú. Napriek tomu, že nástroje na vytváranie súborov pomocníka môžu generovať indexy automaticky, je často lepšie vytvoriť index ručne, pomocou výrazov, ktoré používatelia pravdepodobne budú hľadať.
- 5Vyberte príslušný dokumentačný nástroj. Tlačené alebo PDF používateľské príručky je možné písať v programe na spracovanie textu, ako je Word, alebo v sofistikovanom textovom editore, akým je napríklad FrameMaker, v závislosti od ich dĺžky a zložitosti. Súbory pomoci je možné písať pomocou nástroja na tvorbu pomocníka, ako sú RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix alebo HelpServer.
Metóda 2 z 2: Písanie softvérovej dokumentácie pre koncových používateľov.
- Text by mal byť usporiadaný tak, aby sa dal ľahko čítať, pričom grafika by mala byť umiestnená čo najbližšie k textu, ktorý na ne odkazuje. Logicky rozdeľte dokumentáciu na sekcie a témy. Každá sekcia alebo téma by mala riešiť jeden problém, či už ide o jednu funkciu alebo úlohu jedného programu. Súvisiace problémy je možné podľa potreby vyriešiť pomocou zoznamov „pozri tiež“ alebo hypertextových odkazov.
- Ktorýkoľvek z vyššie uvedených nástrojov dokumentácie môže byť doplnený programom na vytváranie snímok obrazovky, ako je napríklad Snagit, ak dokumentácia vyžaduje množstvo snímok obrazovky. Rovnako ako v prípade inej dokumentácie by mali byť zahrnuté aj snímky obrazovky, ktoré majú pomôcť vysvetliť, ako softvér funguje, a nie oslniť používateľa.
- Tón je obzvlášť dôležitý, najmä pri písaní softvérovej dokumentácie pre koncových používateľov. Oslovujte používateľov pomocou druhej osoby „vy“ namiesto používateľov „tretej osoby“.
- Nástroj na dokumentáciu softvéru/nástroj na tvorbu pomocníka
- Nástroj na vytváranie snímok obrazovky
Prečítajte si tiež: Ako napísať knihu ako tínedžer?
Otázky a odpovede
- Videl som stlačenia klávesov zdokumentované vo viacerých formátoch. Existuje pre položky skutočný štandard alebo sa všetky líšia?Neexistuje univerzálny štandard; Je však dobré stanoviť štandard pre vlastné dokumenty. Niekoľko nápadov nájdete v príručke Microsoft Style of Style (k dispozícii na Amazone) a príručke Apple Style Guide (help.apple.com/applestyleguide/). Majú rôzne štýly, takže ak budete písať dokumentáciu pre viacero platforiem, môže sa stať, že použijete niektoré prvky z jedného sprievodcu a niektoré z iného.
- Existujú nejaké bezplatné nástroje na dokumentáciu softvéru?Skúste Doxygen. Komentujete svoj kód, spustíte Doxygen a máte webovú stránku. Pridajte LaTeX a máte PDF.
