Dobrá dokumentácia k softvéru, či už ide o dokumentáciu k špecifikácii pre programátorov a testery, technické dokumenty pre interných používateľov alebo príručky a súbory pomoci pre koncových používateľov, pomôže používateľom porozumieť funkciám a funkciám softvéru. Dobrá dokumentácia je dokumentácia, ktorá je špecifická, jasná a relevantná a obsahuje všetky informácie, ktoré používateľ potrebuje. Tento článok vás prevedie písaním softvérovej dokumentácie pre technických používateľov a koncových používateľov.
Krok
Metóda 1 z 2: Písanie softvérovej dokumentácie pre technických používateľov
Krok 1. Vedieť, aké informácie zahrnúť
Špecifikačný dokument sa používa ako referenčná príručka pre návrhárov rozhraní, programátorov, ktorí píšu kód, a testerov, ktorí overujú výkonnosť softvéru. Informácie, ktoré je potrebné zahrnúť, budú závisieť od vytváraného programu, ale môžu zahŕňať nasledujúce:
- Dôležité súbory v aplikácii, ako sú súbory vytvorené vývojovým tímom, databázy prístupné počas spustenia programu a aplikácie tretích strán.
- Funkcie a podprogramy vrátane vysvetlenia použitia funkcie/podprogramu, vstupných a výstupných hodnôt.
- Programové premenné a konštanty a spôsob ich použitia.
- Celková štruktúra programu. Pri programoch založených na jednotkách bude možno potrebné popísať každý modul a knižnicu. Alebo ak píšete príručku pre webový program, možno budete musieť vysvetliť, ktoré súbory každá stránka používa.
Krok 2. Rozhodnite, aká úroveň dokumentácie by mala byť prítomná a oddeliteľná od programového kódu
Čím viac technickej dokumentácie je súčasťou kódu programu, tým jednoduchšie bude jeho aktualizácia a údržba, ako aj vysvetlenie rôznych verzií programu. Dokumentácia v kóde programu by mala minimálne zahŕňať použitie funkcií, podprogramov, premenných a konštánt.
- Ak je váš zdrojový kód dlhý, môžete napísať dokumentáciu do súboru pomocníka, ktorý je potom možné indexovať alebo vyhľadávať podľa určitých kľúčových slov. Samostatné súbory dokumentácie sú užitočné, ak je logika programu rozdelená na niekoľko stránok a obsahuje podporné súbory, napríklad webovú aplikáciu.
- Niektoré programovacie jazyky (napríklad Java, Visual Basic. NET alebo C#) majú svoje vlastné štandardy dokumentácie kódu. V takýchto prípadoch sa riaďte štandardnou dokumentáciou, ktorá musí byť súčasťou zdrojového kódu.
Krok 3. Vyberte príslušný dokumentačný nástroj
V niektorých prípadoch je dokumentačný nástroj určený použitým programovacím jazykom. Jazyky C ++, C#, Visual Basic, Java, PHP a ďalšie majú svoje vlastné dokumentačné nástroje. Ak však nie, použité nástroje budú závisieť od požadovanej dokumentácie.
- Na vytváranie textových súborov dokumentov je vhodný textový procesor, ako napríklad Microsoft Word, ak je dokumentácia stručná a jednoduchá. Na vytvorenie dlhej dokumentácie so zložitým textom väčšina technických autorov zvolí špecializovaný dokumentačný nástroj, napríklad Adobe FrameMaker.
- Súbory pomoci pre dokumentovanie zdrojového kódu je možné vytvoriť pomocou programu generátora podporných súborov, 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
Krok 1. Oboznámte sa s obchodnými dôvodmi, ktoré sú základom vytvorenia príručky
Aj keď hlavným dôvodom softvérovej dokumentácie je pomôcť používateľom porozumieť používaniu aplikácie, existuje niekoľko ďalších dôvodov, ktoré môžu byť základom tvorby dokumentácie, napríklad pomoc marketingovému oddeleniu pri predaji aplikácie, zlepšenie imidžu spoločnosti a zníženie technickej podpory. náklady. V niektorých prípadoch je potrebná dokumentácia, ktorá je v súlade s predpismi alebo inými zákonnými požiadavkami.
Dokumentácia však nie je dobrou náhradou za rozhranie. Ak aplikácia vyžaduje na prevádzku veľa dokumentácie, mala by byť navrhnutá tak, aby bola intuitívnejšia
Krok 2. Spoznajte cieľové publikum dokumentácie
Používatelia softvéru majú vo všeobecnosti obmedzené znalosti počítačov nad rámec aplikácií, ktoré používajú. Existuje niekoľko spôsobov, ako splniť ich požiadavky na dokumentáciu:
- Dávajte pozor na titul užívateľa softvéru. Správca systému napríklad vo všeobecnosti rozumie rôznym počítačovým aplikáciám, zatiaľ čo tajomník pozná iba aplikácie, ktoré používa na zadávanie údajov.
- Dávajte pozor na používateľov softvéru. Napriek tomu, že ich pozície sú vo všeobecnosti kompatibilné s vykonávanými úlohami, tieto pozície môžu mať rôzne pracovné zaťaženie, v závislosti od miesta podnikania. Pohovorom s potenciálnymi používateľmi môžete zistiť, či je vaše hodnotenie pracovného zaradenia správne.
- Dávajte pozor na existujúcu dokumentáciu. Dokumentácia a špecifikácie softvérových funkcií môžu ukázať, čo používatelia potrebujú vedieť, aby ich mohli používať. Majte však na pamäti, že používatelia nemusia mať záujem poznať „vnútornosti“programu.
- Zistite, čo je potrebné na dokončenie úlohy a čo je potrebné na to, aby ste ju mohli dokončiť.
Krok 3. Určte vhodný formát dokumentácie
Softvérová dokumentácia môže byť usporiadaná v 1 alebo 2 formátoch, a to referenčné knihy a príručky. Niekedy je dobrým riešením kombinácia týchto dvoch formátov.
- Referenčné formáty sa používajú na popis všetkých funkcií softvéru, ako sú tlačidlá, karty, polia a dialógové okná, a na to, ako fungujú. Niektoré súbory pomocníka sú napísané v tomto formáte, najmä tie, ktoré sú citlivé na kontext. Keď používateľ klikne na Pomocníka na určitej obrazovke, zobrazí sa mu príslušná téma.
- Manuálny formát slúži na vysvetlenie, ako niečo urobiť so softvérom. Príručky sú spravidla v tlačenej alebo PDF verzii, aj keď niektoré stránky pomocníka obsahujú aj pokyny na vykonanie určitých činností. (Manuálne formáty vo všeobecnosti nie sú citlivé na kontext, ale môžu byť prepojené z kontextovo citlivých tém). Príručky sú spravidla vo forme sprievodcu so súhrnom úloh, ktoré sa majú vykonať, v popise a sprievodcovi vo formáte po krokoch.
Krok 4. Rozhodnite o type dokumentácie
Softvérová dokumentácia pre používateľov môže byť zabalená v jednom alebo viacerých z nasledujúcich formátov: tlačené príručky, súbory PDF, súbory pomocníka alebo online pomoc. Každý typ dokumentácie je navrhnutý tak, aby vám ukázal, ako používať funkcie softvéru, či už je to sprievodca alebo návod. Online dokumentácia a stránky pomocníka môžu obsahovať aj ukážkové videá, textové a statické obrázky.
Online súbory pomoci a podpory by mali byť indexované a vyhľadateľné pomocou kľúčových slov, aby používatelia mohli rýchlo nájsť potrebné informácie. Aj keď aplikácia generátora súborov pomocníka môže vytvárať index automaticky, napriek tomu sa odporúča vytvoriť index ručne pomocou bežne vyhľadávaných kľúčových slov
Krok 5. Vyberte príslušný dokumentačný nástroj
Tlačené príručky alebo súbory PDF je možné vytvoriť pomocou programu na spracovanie textu, ako je napríklad Word, alebo pokročilého textového editora, ako je napríklad FrameMaker, v závislosti od dĺžky a zložitosti súboru. Súbory pomoci je možné písať pomocou programu na vytváranie súborov pomocníka, ako sú RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix alebo HelpServer.
Tipy
- Text programovej dokumentácie by mal byť štruktúrovaný tak, aby bol ľahko čitateľný. Umiestnite obrázok čo najbližšie k príslušnému textu. Logicky rozdeľte dokumentáciu podľa sekcií a tém. Každá časť alebo téma by mala popisovať konkrétny problém, úlohy aj funkcie programu. Súvisiace problémy je možné vysvetliť odkazmi alebo zoznammi odkazov.
- Každý z nástrojov dokumentácie popísaných v tomto článku môže byť doplnený programom na vytváranie snímok obrazovky, ako je napríklad SnagIt, ak vaša dokumentácia vyžaduje viac snímok obrazovky. Rovnako ako každá iná dokumentácia by ste mali namiesto „lákania“používateľa obsahovať aj snímky obrazovky, ktoré vám pomôžu vysvetliť, ako aplikácia funguje.
- Venovať pozornosť štýlu je veľmi dôležité, najmä ak píšete softvérovú dokumentáciu pre koncových používateľov. Oslovujte používateľov zámenom „vy“namiesto „používateľ“.
