Jak psát dokumentaci softwaru: 8 kroků

Dobrá softwarová dokumentace - ať už se jedná o dokument obsahující specifikaci požadavků na programátoři nebo testery, technický dokument pro interní uživatele, příručku pro používání softwaru nebo výzvy pro uživatele - pomáhá osobě pracovat se softwarem, porozumět svým charakteristickým rysům a funkce. Postupujte podle tipů - Jak psát dokumentaci softwaru pro technické a koncové uživatele.

Kroky

Metoda 1 z 2:

Softwarová dokumentace pro technické uživatele.

jeden. Určete, které informace musí být uvedeny. Dokumenty o softwarových požadavcích slouží jako referenční příručka pro návrháře uživatelských rozhraní, programátoři, kteří napíše kód a testery, které kontrolují, zda software funguje následovně. Přesné informace závisí na samotném programu, však mohou zahrnovat následující:

Klíčové soubory v aplikaci. Ty mohou být soubory vytvořené vývojářským týmem, databázemi způsobené během operace softwaru a programy služby třetí strany.
Funkce a podprogramy. Je zde uvedeno, že každá funkce a podprogram se provádí, včetně vstupních a výstupních hodnot.
Softwarové proměnné a konstantní a jak se používají v aplikaci.
Obecná struktura programu. U aplikací založených na disku budete pravděpodobně potřebovat popis jednotlivých bloků a programových knihoven, zatímco webové aplikace budou potřebovat popis stránek, které používají soubory.

Obrázek s názvem Zápis Softwarová dokumentace Krok 2

2. Rozhodněte se, kolik dokumentace by mělo být v kódu programu a kolik by mělo být odděleno. Čím více technické dokumentace je vytvořena v kódu programu, tím snadnější bude tento kód aktualizovat jako dokumentaci týkající se různých verzí původní aplikace. Minimálně, dokumentace v kódu programu by měla vysvětlit funkce, podprogramy, konstanty a proměnné softwaru.

Pokud je kódový kód poměrně dlouhý, může být umístěn jako referenční soubor, ve kterém můžete vyhledávat podle klíčových slov nebo rozcestníků. Bude to velký plus pro aplikace, kde je logika programu rozdělena na mnoho stránek a obsahuje pomocná čísla souborů, jako v určitých webových aplikacích.

Některé programovací jazyky, jako je Java nebo Net Framework (jazyka.NET, C #), mají vlastní normy pro kód dokumentace. V takových případech postupujte podle standardních pokynů - kolik dokumentace by mělo být zahrnuto do kódu programu.

Obrázek s názvem Write Software Documentation Krok 3

3. Vyberte si vhodný nástroj. Do jisté míry je to definováno jazykem, na kterém je kód napsán, ať už je to C ++, C #, jazyka, Java nebo PHP - pro každého je naším vlastním nástrojem. V jiných případech je použitý nástroj určen typem požadované dokumentace.

Text Editor "Microsoft Word" -Cercing nástroj pro vytváření samostatných textových souborů dokumentace, která bude jednoduchá a stručná. Pro dlouhé textové soubory, mnoho technických vývojářů dokumentace dávají přednost zvolení programu Adobe FrameMaker.

Tip soubory pro dokumentaci kódu softwaru lze psát pomocí libovolného nástroje, jako je Robohelp, nápověda a manuál, Doc-To-Help, Madcap Flare, nebo "Helplogix".

Metoda 2 z 2:

Psaní softwarová dokumentace pro koncové uživatele

jeden. Identifikujte obchodní úvahy pro vaši dokumentaci. Ačkoli funkční důvody pro softwarovou dokumentaci pomáhají uživatelům pochopit, jak používat aplikaci, existují i jiné důvody, jako například pomoc při podpoře zboží na trhu, zlepšení obrazu společnosti a nejdůležitější věcí, snižování nákladů na technickou podporu. V některých případech je dokumentace povinna dodržovat určitá pravidla a právní požadavky.

V žádném případě by programová dokumentace neměla nahradit špatný design rozhraní. Pokud obrazovka aplikace vyžaduje mnoho vysvětlující dokumentace, je lepší změnit návrh na něco intuitivnějšího.

Obrázek s názvem Write Software Documentation Krok 5

2. Porozumět publiku, pro které píšete dokumentaci. Ve většině případů uživatelé softwaru znají málo o počítačích kromě aplikačních úkolů. Existuje několik způsobů, jak určit, jak koordinovat své potřeby s dokumentací.

Podívejte se na profese ve vlastnictví vašich potenciálních uživatelů. Správce systému bude pravděpodobně odborníkem v používání softwarových aplikací, zatímco operátor zadávání dat bude pravděpodobně vlastní aplikaci, že ji nebo v současné době používá pro zadávání dat.

Podívejte se na samotné uživatele. I když jejich příspěvky obecně určují, co se lidé angažují, ale existují významné rozdíly v tom, jak se v této organizaci používají určité pozice. Provádění rozhovoru s potenciálními uživateli, můžete přidat svůj názor - Má jméno funkce plnil povinnosti.

Viz existující dokumentace. Dokumentace pro předchozí verze softwaru dává přibližný koncept, že uživatel potřebuje vědět o používání programu. Nezapomeňte však, že koncoví uživatelé nemají zájem o to, jak program funguje, je důležité, aby s tím mohou vědět, co mohou dělat.

Určete úkoly, které jsou nezbytné pro tuto práci a jaké úkoly musí být provedeny před provedením těchto úkolů.

Obrázek s názvem Write Software Documentation Krok 6

3. Určete příslušné formát (y) dokumentace. Softwarová dokumentace může být strukturována v jednom ze dvou formátů - referenční příručky a pokyny pro použití. Někdy je lepší zvolit smíšenou verzi těchto dvou formátů.

Referenční příručka je navržena tak, aby vysvětlila nástroje softwaru (tlačítka, tabulky, pole a dialogové okno) a jak to Toolkit funguje. V tomto formátu jsou napsány mnoho rychlých souborů a zobrazí kontextová výzva k zobrazení požadovaného tématu po klepnutí na tlačítko "Nápověda" na požadované obrazovce.

Pokyny pro použití vysvětluje, jak používat software k provedení konkrétního úkolu. Použití instrukce má často tištěný průvodce nebo formát PDF, i když některé výzvy zahrnují témata, jak provést konkrétní úkol. (Tato referenční témata obvykle nejsou kontextová, i když mohou být hypertextové odkazy) Použití instrukce má často formulář referenční knihy s popisem úkolu a instrukcí krok za krokem.

Obrázek s názvem Write Software Documentation Krok 7

4. Rozhodněte se, který formát (formátů) dokumentace by měly být. Softwarová dokumentace pro koncové uživatele může být jeden nebo více formátů: Průvodce tisku, dokumenty ve formátu PDF, Tip souborů nebo online nápovědy. Každá z těchto formátů je vytvořen tak, aby zobrazoval uživatele, jak používat každý program programu - být stručný přehled nebo průvodce. Stejně jako v případě rychlých souborů a nápovědy online může mít dokumentace demonstrační video nebo text s obrázky.

Tipy a online soubory nápovědy musí mít ukazatele, hledat podle klíčových slov, což umožní uživateli rychle najít požadované informace. Ačkoli nástroje pro rychlé soubory mohou automaticky vytvářet ukazatele, je lepší to udělat ručně pomocí podmínek, které uživatelé budou s největší pravděpodobností vyhledávat.

Obrázek s názvem Write Software Documentation Krok 8

Pět. Vyberte vhodný nástroj pro vytváření dokumentace. Provozní příručky nebo formát PDF lze psát v textových editorů, jako jsou "Word" nebo "FrameMaker", v závislosti na délce a složitosti manuálu. Soubory tipů lze psát pomocí takových vývojových nástrojů, jako je "Robohellp", "Nápověda a manuál", "Doc-To-Help", "Flare", "Helplogix" nebo "HelpServer".

Tipy

Text by měl být snadno čitelný, snímky by měly být umístěny co nejblíže textu, ke kterému patří. Zasuňte dokumentaci pro sekce a logické motivy. Každá sekce nebo téma by se mělo týkat určité otázky, ať už je to jeden program nebo úkol. Související otázky by měly být uvedeny "sledovat také" s hypertextovým odkazem, v případě potřeby.
Všechny nástroje pro vytváření dokumentace, které byly uvedeny výše, mohou být doplněny programem Screenshots, například Snagit, pokud dokumentace vyžaduje určitý počet screenshotů. Stejně jako u druhé dokumentace by Screenshots měly vysvětlit, jak software funguje, a ne zavádět uživatele.
Důležité je také tón psaní dokumentace, zejména pokud je napsáno pro koncové uživatele. Použijte druhou tvář "vy", namísto třetí strany "uživatelů".

Co potřebuješ

Nástroj pro psaní dokumentace / debula
Nástroj pro vytváření screenshotů