Ako písať softvérovú dokumentáciu: 8 krokov (s obrázkami)

Dobrá softvérová dokumentácia, či už ide o dokument so špecifikáciami pre programátorov a testerov, technický dokument pre interných používateľov alebo softvérové príručky a súbory nápovedy pre koncových používateľov, pomáha človeku pracujúcemu so softvérom pochopiť jeho vlastnosti a funkcie. 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.[1]
Nasledujú pokyny, ako pí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


Určite, aké informácie je potrebné zahrnúť. Dokumenty špecifikácie softvéru 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 daného programu, ale môžu zahŕňať niektorú z nasledujúcich informácií:

  • Kľúčové súbory v rámci aplikácie. Môže ísť o súbory vytvorené vývojovým tímom, databázy, ku ktorým sa pristupuje počas prevádzky programu, a obslužné programy tretích strán.
  • Funkcie a podprogramy. To zahŕňa vysvetlenie, čo robí každá funkcia alebo podprogram vrátane rozsahu vstupných hodnôt 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ť opis jednotlivých modulov a knižníc programu, zatiaľ čo v prípade webovej aplikácie to môže znamenať opis, ktoré stránky používajú ktoré súbory.


Rozhodnite, koľko dokumentácie by malo byť v rámci programového kódu a koľko by malo byť oddelené od neho. Čím viac technickej dokumentácie sa na začiatku vytvorí v rámci zdrojového kódu programu, tým ľahšie sa bude aktualizovať a udržiavať spolu s kódom, ako aj dokumentovať rôzne verzie pôvodnej aplikácie. Dokumentácia v rámci zdrojového kódu musí minimálne vysvetľovať účel funkcií, podprogramov, premenných a konštánt.[2]

  • Ak je zdrojový kód obzvlášť dlhý, možno ho zdokumentovať vo forme súboru nápovedy, ktorý možno indexovať alebo vyhľadávať pomocou kľúčových slov. Je to výhodné najmä v prípade aplikácií, ktorých logika programu je roztrieštená na mnoho stránok a obsahuje množstvo doplnkových súborov, ako je to v prípade niektorých webových aplikácií.
  • Niektoré programovacie jazyky, ako napr .NET Framework (Visual Basic.NET, C #), majú svoje vlastné štandardy pre dokumentáciu kódu. V týchto prípadoch sa riaďte štandardmi, pokiaľ ide o to, aká časť dokumentácie by mala byť súčasťou zdrojového kódu.


Vyberte si vhodný dokumentačný nástroj. Do určitej miery to závisí od jazyka, v ktorom je kód napísaný, či už ide o C++, C#, Visual Basic, Java alebo PHP, pretože pre tieto a ďalšie jazyky existujú špecifické nástroje. V iných prípadoch je použitie nástroja určené typom požadovanej dokumentácie.

  • Programy na spracovanie textu Microsoft Word sú vhodné na vytváranie samostatný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 mnohí technickí autori uprednostňujú dokumentačný nástroj, ako je napríklad Adobe FrameMaker.
  • Súbory nápovedy na dokumentovanie zdrojového kódu možno vytvoriť pomocou akéhokoľvek nástroja na tvorbu nápovedy, napríklad 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


Určenie obchodných dôvodov pre vašu dokumentáciu. Hoci funkčným dôvodom dokumentácie softvéru je pomôcť používateľom pochopiť, ako používať aplikáciu, existujú aj iné dôvody, napríklad pomoc pri marketingu softvéru, zlepšenie imidžu spoločnosti a najmä zníženie nákladov na technickú podporu.[3]
V niektorých prípadoch je dokumentácia potrebná na splnenie určitých predpisov alebo iných právnych požiadaviek.

  • V žiadnom prípade by však dokumentácia softvéru nemala nahrádzať zlý návrh rozhrania. Ak si obrazovka aplikácie vyžaduje množstvo dokumentácie na jej vysvetlenie, je lepšie zmeniť dizajn obrazovky na niečo intuitívnejšie.


Pochopte publikum, pre ktoré dokumentáciu píšete. Vo väčšine prípadov majú používatelia softvéru len malé znalosti o počítačoch mimo aplikácií, ktoré používajú. Existuje niekoľko spôsobov, ako určiť, ako sa s vašou dokumentáciou vysporiadať s ich potrebami.

  • Pozrite sa na pracovné pozície, ktoré majú vaši potenciálni používatelia. Správca systému je pravdepodobne odborníkom na viaceré softvérové aplikácie, zatiaľ čo pracovník zadávajúci údaje bude skôr poznať len aplikáciu, ktorú v súčasnosti používa na zadávanie údajov.
  • Pozrite sa na samotných používateľov. Hoci názvy pracovných pozícií vo všeobecnosti označujú, čo ľudia robia, môžu existovať značné rozdiely v tom, ako sa určité názvy používajú v rámci danej organizácie. Rozhovorom s potenciálnymi používateľmi môžete zistiť, či sú vaše dojmy o tom, čo naznačuje ich pracovná pozícia, presné alebo nie.
  • Pozrite sa na existujúcu dokumentáciu. Dokumentácia k predchádzajúcim verziám softvéru, ako aj funkčné špecifikácie poskytujú určité informácie o tom, čo bude používateľ potrebovať vedieť, aby mohol program používať. Majte však na pamäti, že koncových používateľov nezaujíma ani tak to, ako program funguje, ako to, čo pre nich môže urobiť.
  • Identifikujte úlohy potrebné na vykonávanie práce a aké úlohy je potrebné vykonať pred tým, ako sa tieto úlohy môžu vykonať.


Určite vhodný formát (formáty) dokumentácie. Softvérová dokumentácia môže byť štruktúrovaná v 1 z 2 formátov, referenčná príručka a používateľská príručka. 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. Mnohé súbory nápovedy sú napísané v tomto formáte, najmä kontextová nápoveda, ktorá zobrazí príslušnú tému vždy, keď používateľ klikne na tlačidlo nápovedy na určitej obrazovke.[4]
  • Formát používateľskej príručky vysvetľuje, ako používať softvér na vykonanie konkrétnej úlohy. Používateľské príručky sú často formátované ako tlačené príručky alebo súbory PDF, hoci niektoré súbory nápovedy obsahujú témy o tom, ako vykonávať konkrétne úlohy. (Tieto témy nápovedy zvyčajne nie sú kontextovo citlivé, hoci na ne môžu viesť hypertextové odkazy z tém, ktoré sú.) Používateľské príručky majú často formu návodov, pričom v úvode je zhrnutie úloh, ktoré sa majú vykonať, a pokyny sú uvedené v očíslovaných krokoch.[5]


Rozhodnite sa, akú formu (formy) by mala dokumentácia mať. Softvérová dokumentácia pre koncových používateľov môže mať 1 alebo niekoľko z mnohých foriem: tlačené príručky, dokumenty PDF, súbory nápovedy alebo online nápoveda. Každý formulár je navrhnutý tak, aby používateľovi ukázal, ako používať jednotlivé funkcie programu, či už vo forme návodu na použitie alebo tutoriálu; v prípade súborov nápovedy a online nápovedy to môže zahŕňať demonštračné videá, ako aj text a 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ú. Hoci nástroje na tvorbu súborov nápovedy môžu generovať indexy automaticky, často je lepšie vytvoriť index ručne s použitím výrazov, ktoré používatelia pravdepodobne vyhľadávajú.

  • Výber vhodného dokumentačného nástroja. Tlačené používateľské príručky alebo príručky vo formáte PDF môžu byť napísané pomocou programu na spracovanie textu, ako je Word, alebo sofistikovaného textového editora, ako je FrameMaker, v závislosti od ich dĺžky a zložitosti. Súbory nápovedy možno napísať pomocou nástroja na tvorbu nápovedy, napríklad RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix alebo HelpServer.
  • Odkazy