Dobrá softwarová dokumentace, ať už jde o dokumentaci specifikací pro programátory a testery, technické dokumenty pro interní uživatele nebo příručky a soubory nápovědy pro koncové uživatele, pomůže uživatelům porozumět funkcím a funkcím softwaru. Dobrá dokumentace je dokumentace, která je konkrétní, jasná a relevantní, se všemi informacemi, které uživatel potřebuje. Tento článek vás provede psaním softwarové dokumentace pro technické uživatele a koncové uživatele.
Krok
Metoda 1 ze 2: Psaní softwarové dokumentace pro technické uživatele
Krok 1. Zjistěte, jaké informace zahrnout
Dokument specifikace se používá jako referenční příručka pro návrháře rozhraní, programátory, kteří píší kód, a testery, kteří ověřují výkonnost softwaru. Informace, které je třeba zahrnout, budou záviset na vytvářeném programu, ale mohou zahrnovat následující:
- Důležité soubory v aplikaci, jako jsou soubory vytvořené vývojovým týmem, databáze přístupné za běhu programu a aplikace třetích stran.
- Funkce a podprogramy, včetně vysvětlení použití funkce/podprogramu, vstupní a výstupní hodnoty.
- Programové proměnné a konstanty a způsob jejich použití.
- Celková struktura programu. U programů založených na jednotce může být nutné popsat každý modul a knihovnu. Nebo pokud píšete příručku pro webový program, možná budete muset vysvětlit, jaké soubory jednotlivé stránky používají.
Krok 2. Rozhodněte, jaká úroveň dokumentace by měla být přítomna a oddělitelná od kódu programu
Čím více technické dokumentace je součástí kódu programu, tím snazší bude jeho aktualizace a údržba a vysvětlení různých verzí programu. Minimálně by dokumentace v programovém kódu měla zahrnovat použití funkcí, podprogramů, proměnných a konstant.
- Pokud je váš zdrojový kód dlouhý, můžete napsat dokumentaci do souboru nápovědy, který lze poté indexovat nebo vyhledávat s určitými klíčovými slovy. Samostatné soubory dokumentace jsou užitečné, pokud je logika programu rozdělena na několik stránek a obsahuje soubory podpory, například webovou aplikaci.
- Některé programovací jazyky (například Java, Visual Basic. NET nebo C#) mají své vlastní standardy dokumentace kódu. V takových případech se řiďte standardní dokumentací, která musí být součástí zdrojového kódu.
Krok 3. Vyberte příslušný dokumentační nástroj
V některých případech je dokumentační nástroj určen použitým programovacím jazykem. Jazyky C ++, C#, Visual Basic, Java, PHP a další mají své vlastní dokumentační nástroje. Pokud tomu tak není, použité nástroje budou záviset na požadované dokumentaci.
- Textový procesor, jako je Microsoft Word, je vhodný pro vytváření textových souborů dokumentu, pokud je dokumentace stručná a jednoduchá. Chcete -li vytvořit dlouhou dokumentaci se složitým textem, většina technických autorů zvolí specializovaný dokumentační nástroj, například Adobe FrameMaker.
- Soubory nápovědy pro dokumentaci zdrojového kódu lze vytvořit pomocí programu generátoru podpůrných souborů, například RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare nebo HelpLogix.
Metoda 2 ze 2: Psaní softwarové dokumentace pro koncové uživatele
Krok 1. Seznamte se s obchodními důvody, které jsou podkladem pro vytvoření manuálu
Přestože hlavním důvodem softwarové dokumentace je pomoci uživatelům porozumět používání aplikace, existuje několik dalších důvodů, které mohou být základem tvorby dokumentace, například pomoc marketingovému oddělení při prodeji aplikace, zlepšení image společnosti a omezení technické podpory. náklady. V některých případech je vyžadována dokumentace, aby byla v souladu s předpisy nebo jinými zákonnými požadavky.
Dokumentace však není dobrou náhradou za rozhraní. Pokud aplikace ke svému provozu vyžaduje velké množství dokumentace, měla by být navržena tak, aby byla intuitivnější
Krok 2. Poznejte cílové publikum dokumentace
Uživatelé softwaru mají obecně omezené znalosti o počítači nad rámec aplikací, které používají. Existuje několik způsobů, jak splnit jejich požadavky na dokumentaci:
- Věnujte pozornost názvu uživatele softwaru. Správce systému například obecně rozumí různým počítačovým aplikacím, zatímco tajemník zná pouze aplikace, které používá k zadávání dat.
- Věnujte pozornost uživatelům softwaru. Přestože jsou jejich pozice obecně kompatibilní s prováděnými úkoly, mohou mít tyto pozice různé pracovní vytížení v závislosti na místě podnikání. Pohovorem s potenciálními uživateli můžete zjistit, zda je vaše hodnocení pracovního zařazení správné.
- Věnujte pozornost stávající dokumentaci. Dokumentace a specifikace softwarových funkcí mohou ukázat, co uživatelé potřebují vědět, aby je mohli používat. Mějte však na paměti, že uživatelé nemusí mít zájem znát „vnitřnosti“programu.
- Zjistěte, co je potřeba k dokončení úkolu a co je potřeba k jeho dokončení.
Krok 3. Určete příslušný formát dokumentace
Softwarovou dokumentaci lze uspořádat v 1 nebo 2 formátech, konkrétně v příručkách a příručkách. Někdy je dobrým řešením kombinace těchto dvou formátů.
- Referenční formáty se používají k popisu všech funkcí softwaru, jako jsou tlačítka, karty, pole a dialogová okna, a jejich fungování. Některé soubory nápovědy jsou zapsány v tomto formátu, zejména ty, které jsou citlivé na kontext. Když uživatel klikne na Nápovědu na určité obrazovce, obdrží příslušné téma.
- Manuální formát slouží k vysvětlení, jak se softwarem něco udělat. Manuály jsou obvykle v tištěném nebo PDF formátu, i když některé stránky nápovědy obsahují také pokyny k provádění určitých věcí. (Ruční formáty obecně nejsou kontextově citlivé, ale mohou být propojeny s kontextově citlivými tématy). Příručky jsou obvykle ve formě příručky se souhrnem úkolů, které je třeba provést, v popisu a příručce ve formátu po krocích.
Krok 4. Rozhodněte o typu dokumentace
Softwarová dokumentace pro uživatele může být zabalena v jednom nebo více z následujících formátů: tištěné příručky, soubory PDF, soubory nápovědy nebo online nápověda. Každý typ dokumentace je navržen tak, aby vám ukázal, jak používat funkce softwaru, ať už jde o průvodce nebo výukový program. Online dokumentace a stránky nápovědy mohou také obsahovat ukázková videa, text a statické obrázky.
Soubory online nápovědy a podpory by měly být indexovány a prohledávány pomocí klíčových slov, aby uživatelé mohli rychle najít potřebné informace. Přestože aplikace generátoru souborů nápovědy může vytvořit index automaticky, přesto se doporučuje vytvořit index ručně pomocí běžně vyhledávaných klíčových slov
Krok 5. Vyberte příslušný dokumentační nástroj
Tištěné příručky nebo soubory PDF lze vytvořit pomocí programu pro zpracování textu, jako je Word, nebo pokročilého textového editoru, jako je například FrameMaker, v závislosti na délce a složitosti souboru. Soubory nápovědy lze zapisovat pomocí programu pro vytváření souborů nápovědy, jako jsou RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix nebo HelpServer.
Tipy
- Text dokumentace k programu by měl být strukturován tak, aby byl snadno čitelný. Umístěte obrázek co nejblíže příslušnému textu. Logicky rozdělte dokumentaci podle sekcí a témat. Každá část nebo téma by mělo popisovat konkrétní problém, funkce úkolu i programu. Související problémy lze vysvětlit odkazy nebo seznamy odkazů.
- Každý z nástrojů dokumentace popsaných v tomto článku může být doplněn programem pro vytváření screenshotů, například SnagIt, pokud vaše dokumentace vyžaduje více screenshotů. Jako každá jiná dokumentace byste měli místo „lákat“uživatele také obsahovat screenshoty, které vám pomohou vysvětlit, jak aplikace funguje.
- Věnování pozornosti stylu je velmi důležité, zvláště pokud píšete softwarovou dokumentaci pro koncové uživatele. Oslovujte uživatele pomocí zájmena „vy“místo „uživatel“.
