Softwarová dokumentace - Software documentation

Softwarová dokumentace je psaný text nebo ilustrace, která doprovází počítačový software nebo je vložena do zdrojového kódu. Dokumentace buď vysvětluje, jak software funguje, nebo jak ho používá, a může znamenat různé věci pro lidi v různých rolích.

Dokumentace je důležitou součástí softwarového inženýrství . Mezi typy dokumentace patří:

  • Požadavky - Prohlášení, která identifikují atributy, schopnosti, vlastnosti nebo kvality systému. Toto je základ toho, co bude nebo bylo implementováno.
  • Architektura/design - přehled softwaru. Zahrnuje vztahy k prostředí a konstrukční principy, které mají být použity při návrhu softwarových komponent.
  • Technická - dokumentace kódu, algoritmů, rozhraní a API .
  • Koncový uživatel -příručky pro koncového uživatele, správce systému a pracovníky podpory.
  • Marketing - Jak uvést produkt na trh a analýza poptávky na trhu.

Dokumentace požadavků

Dokumentace požadavků je popis toho, co konkrétní software dělá nebo má dělat. Během vývoje se používá ke komunikaci, jak software funguje nebo jak má fungovat. Používá se také jako dohoda nebo jako základ pro dohodu o tom, co software bude dělat. Požadavky produkuje a spotřebovává každý, kdo se podílí na výrobě softwaru, včetně: koncových uživatelů , zákazníků , projektových manažerů , prodeje , marketingu , softwarových architektů , techniků použitelnosti , návrhářů interakcí , vývojářů a testerů .

Požadavky přicházejí v různých stylech, zápisech a formalitách. Požadavky mohou být podobné cílům (např. Distribuované pracovní prostředí ), blízké designu (např. Sestavení lze spustit kliknutím pravým tlačítkem na konfigurační soubor a výběrem funkce „build“ ) a čímkoli mezi tím. Mohou být specifikovány jako prohlášení v přirozeném jazyce , jako nakreslené obrázky, jako podrobné matematické vzorce a jako jejich kombinace.

Variabilita a složitost dokumentace požadavků z ní činí osvědčenou výzvu. Požadavky mohou být implicitní a těžko odhalitelné. Je těžké přesně vědět, kolik a jaký druh dokumentace je potřeba a kolik může být ponecháno na dokumentaci architektury a návrhu, a je obtížné vědět, jak dokumentovat požadavky vzhledem k různorodosti lidí, kteří by měli číst a používat dokumentaci. . Dokumentace požadavků je tedy často neúplná (nebo neexistuje). Bez náležité dokumentace požadavků jsou změny softwaru obtížnější-a proto náchylnější k chybám (snížená kvalita softwaru ) a časově náročné (drahé).

Potřeba dokumentace požadavků obvykle souvisí se složitostí produktu, dopadem produktu a délkou životnosti softwaru. Pokud je software velmi složitý nebo je vyvíjen mnoha lidmi (např. Software pro mobilní telefony), mohou požadavky pomoci lépe komunikovat, čeho dosáhnout. Pokud je software kritický z hlediska bezpečnosti a může mít negativní dopad na lidský život (např. Jaderné energetické systémy, lékařská zařízení, mechanická zařízení), často je vyžadována formálnější dokumentace požadavků. Pokud se od softwaru očekává, že bude žít pouze měsíc nebo dva (např. Velmi malé aplikace pro mobilní telefony vyvinuté speciálně pro určitou kampaň), může být zapotřebí velmi malá dokumentace požadavků. Pokud je software prvním vydáním, na kterém se později staví, je dokumentace požadavků velmi užitečná při správě změny softwaru a ověřování, že při jeho úpravě nebylo v softwaru nic poškozeno.

Tradičně jsou požadavky specifikovány v dokumentech požadavků (např. Pomocí aplikací pro zpracování textu a tabulkových procesorů). Ke správě zvýšené složitosti a měnící se povahy dokumentace požadavků (a softwarové dokumentace obecně) jsou podporovány systémy zaměřené na databázi a nástroje pro správu účelových požadavků .

Dokumentace architektonického návrhu

Architektonická dokumentace (také známá jako popis softwarové architektury ) je speciální typ designového dokumentu. Svým způsobem jsou dokumenty architektury třetím derivátem kódu ( dokument návrhu je druhým derivátem a dokumenty kódu jsou prvním). Velmi málo v dokumentech architektury je specifické pro samotný kód. Tyto dokumenty nepopisují, jak konkrétní rutinu naprogramovat, ani proč tato konkrétní rutina existuje ve formě, ve které existuje, ale pouze stanoví obecné požadavky, které by existenci takové rutiny motivovaly. Dobrý dokument o architektuře je krátký na detaily, ale silný na vysvětlení. Může navrhovat přístupy k návrhu nižší úrovně, ale skutečné průzkumné obchodní studie ponechte na jiných dokumentech.

Dalším typem dokumentu návrhu je srovnávací dokument nebo obchodní studie. To by často mělo formu whitepaperu . Zaměřuje se na jeden konkrétní aspekt systému a navrhuje alternativní přístupy. Může to být na úrovni uživatelského rozhraní , kódu, designu nebo dokonce architektonické úrovně. Načrtne, jaká je situace, popíše jednu nebo více alternativ a vyjmenuje klady a zápory každé z nich. Dobrý obchodní studijní dokument je náročný na výzkum, jasně vyjadřuje jeho myšlenku (aniž by se silně spoléhal na tupý žargon, aby oslňoval čtenáře), a hlavně je nestranný. Měl by upřímně a jasně vysvětlit náklady jakéhokoli řešení, které nabízí jako nejlepší. Cílem obchodní studie je navrhnout nejlepší řešení, než prosazovat konkrétní úhel pohledu. Je naprosto přijatelné neučinit žádný závěr nebo dojít k závěru, že žádná z alternativ není dostatečně lepší než základní linie, aby byla zaručena změna. Mělo by se k tomu přistupovat jako k vědeckému úsilí, ne jako k marketingové technice.

Velmi důležitou součástí návrhu dokumentu ve vývoji podnikového softwaru je dokument DDD (Database Design Document). Obsahuje prvky koncepčního, logického a fyzického návrhu. DDD obsahuje formální informace, které lidé, kteří interagují s databází, potřebují. Účelem jeho přípravy je vytvořit společný zdroj, který budou používat všichni hráči ve scéně. Potenciálními uživateli jsou:

Když hovoříme o relačních databázových systémech, dokument by měl obsahovat následující části:

  • Entita - schéma vztahu ( vylepšené nebo ne), včetně následujících informací a jejich jasných definic:
    • Sady entit a jejich atributy
    • Vztahy a jejich atributy
    • Klíče kandidátů pro každou sadu entit
    • Omezení na základě atributů a řazené kolekce členů
  • Relační schéma včetně následujících informací:
    • Tabulky, atributy a jejich vlastnosti
    • Pohledy
    • Omezení, jako jsou primární klíče, cizí klíče,
    • Mohutnost referenčních omezení
    • Kaskádové zásady pro referenční omezení
    • Primární klíče

Je velmi důležité zahrnout všechny informace, které mají použít všichni herci ve scéně. Je také velmi důležité aktualizovat dokumenty, protože k jakékoli změně dochází také v databázi.

Technická dokumentace

Je důležité, aby dokumenty kódu přidružené ke zdrojovému kódu (což může zahrnovat soubory README a dokumentaci API ) byly důkladné, ale ne tak podrobné, aby jejich údržba byla příliš časově náročná nebo obtížná. Běžně se nacházejí různé návody k dokumentaci a přehledům specifické pro softwarovou aplikaci nebo softwarový produkt dokumentovaný autory API . Tuto dokumentaci mohou používat vývojáři, testeři a také koncoví uživatelé. Dnes je k vidění mnoho špičkových aplikací v oblasti energetiky, energetiky, dopravy, sítí, letectví, bezpečnosti, zabezpečení, průmyslové automatizace a řady dalších domén. Technická dokumentace se v takových organizacích stala důležitou, protože základní a pokročilá úroveň informací se může v průběhu času měnit se změnami architektury.

Dokumenty kódu jsou často uspořádány do stylu referenční příručky , což umožňuje programátorovi rychle vyhledat libovolnou funkci nebo třídu.

Technická dokumentace vložená do zdrojového kódu

Často nástroje , jako Doxygen , NDoc , Visual Expert , Javadoc , JSDoc , EiffelStudio , Sandcastle , ROBODoc , POD , TwinText nebo univerzální zprávy mohou být použity pro automatické generování kódu dokladů-to znamená, že extrahovat komentáře a softwarových zakázek , je -li k dispozici, ze zdrojového kódu a vytvořte referenční příručky v takových formách, jako jsou textové nebo HTML soubory.

Myšlenka automaticky generující dokumentace je pro programátory atraktivní z různých důvodů. Protože je například extrahován ze samotného zdrojového kódu (například prostřednictvím komentářů ), může jej programátor napsat při odkazování na kód a použít stejné nástroje, které byly použity k vytvoření zdrojového kódu k vytvoření dokumentace. Díky tomu je mnohem snazší udržovat dokumentaci aktuální.

Samozřejmě nevýhodou je, že tento druh dokumentace mohou upravovat pouze programátoři a záleží na nich, zda obnoví výstup (například spuštěním úlohy cron k aktualizaci dokumentů každou noc). Někteří by to charakterizovali spíše jako pro, než jako proti.

Gramotné programování

Respektovaný počítačový vědec Donald Knuth poznamenal, že dokumentace může být velmi obtížným procesem po promyšlení, a obhajoval gramotné programování , psané ve stejnou dobu a na stejném místě jako zdrojový kód a extrahované automatickými prostředky. Programovací jazyky Haskell a CoffeeScript mají integrovanou podporu pro jednoduchou formu gramotného programování, ale tato podpora není příliš využívána.

Elucidativní programování

Elucidativní programování je výsledkem praktických aplikací gramotného programování v reálných kontextech programování. Elucidativní paradigma navrhuje, aby zdrojový kód a dokumentace byly uloženy odděleně.

Vývojáři softwaru často musí být schopni vytvářet a přistupovat k informacím, které nebudou součástí samotného zdrojového souboru. Takové anotace jsou obvykle součástí několika aktivit vývoje softwaru, jako je procházení kódu a portování, kde je zdrojový kód třetí strany funkčně analyzován. Anotace proto mohou vývojáři pomoci v jakékoli fázi vývoje softwaru, kde by formální dokumentační systém bránil pokroku.

Uživatelská dokumentace

Na rozdíl od kódových dokumentů uživatelské dokumenty jednoduše popisují, jak se program používá.

V případě softwarové knihovny mohou být kódové dokumenty a uživatelské dokumenty v některých případech skutečně rovnocenné a stojí za to je spojit, ale pro obecnou aplikaci to často není pravda.

Uživatelská dokumentace obvykle popisuje každou funkci programu a pomáhá uživateli při realizaci těchto funkcí. Je velmi důležité, aby uživatelské dokumenty nebyly matoucí a aby byly aktuální. Uživatelské dokumenty nemusí být nijak zvlášť organizovány, ale je velmi důležité, aby měly důkladný rejstřík . Konzistence a jednoduchost jsou také velmi cenné. Uživatelská dokumentace je považována za smlouvu určující, co bude software dělat. Spisovatelé API jsou velmi dobře připraveni na psaní dobrých uživatelských dokumentů, protože by dobře věděli o architektuře softwaru a použitých programovacích technikách. Viz také technické psaní .

Uživatelskou dokumentaci lze vytvářet v různých online a tištěných formátech. Existují však tři široké způsoby, jak lze organizovat uživatelskou dokumentaci.

  1. Kurz: Přístup k tutoriálu je považován za nejužitečnější pro nového uživatele, ve kterém je proveden každým krokem plnění konkrétních úkolů.
  2. Tematické: tematický přístup, kde kapitoly nebo sekce soustředit na jednu konkrétní oblast zájmu, je obecnější použití k mezilehlé uživatele. Někteří autoři dávají přednost sdělování svých myšlenek prostřednictvím článku založeného na znalostech, aby usnadnili potřeby uživatelů. Tento přístup obvykle praktikuje dynamické odvětví, například informační technologie .
  3. Seznam nebo reference: Konečný typ organizačního principu je ten, ve kterém jsou příkazy nebo úkoly jednoduše seřazeny podle abecedy nebo logicky, často prostřednictvím křížových odkazů. Tento druhý přístup je užitečnější pro pokročilé uživatele, kteří přesně vědí, jaký druh informací hledají.

Běžnou stížností uživatelů ohledně softwarové dokumentace je, že pouze jeden z těchto tří přístupů byl přijat k téměř vyloučení ostatních dvou. Je běžné omezit poskytnutou dokumentaci softwaru pro osobní počítače na online nápovědu, která poskytuje pouze referenční informace o příkazech nebo položkách nabídky. Doučování nových uživatelů nebo pomoc zkušenějším uživatelům vytěžit z programu maximum je ponecháno na soukromých vydavatelích, kterým vývojář softwaru často poskytuje značnou pomoc.

Skládání uživatelské dokumentace

Stejně jako ostatní formy technické dokumentace, i dobrá uživatelská dokumentace těží z organizovaného procesu vývoje. V případě uživatelské dokumentace se proces, jak se běžně vyskytuje v průmyslu, skládá z pěti kroků:

  1. Analýza uživatelů , základní fáze výzkumu procesu.
  2. Plánování nebo fáze vlastní dokumentace.
  3. Přezkoumání konceptu, fáze s vysvětlením, kde se hledá zpětná vazba na návrh složený v předchozím kroku.
  4. Testování použitelnosti , přičemž použitelnost dokumentu je testována empiricky.
  5. Úpravy , konečný krok, ve kterém jsou informace shromážděné v krocích tři a čtyři použity k vytvoření konečného návrhu.

Dokumentace a kontroverze agilního vývoje

„Odolnost vývojářů vůči dokumentaci je dobře známá a nevyžaduje žádný důraz.“ Tato situace je zvláště převládající v agilním vývoji softwaru, protože tyto metodiky se snaží vyhnout se jakýmkoli zbytečným činnostem, které přímo nepřinášejí hodnotu. Konkrétně se jedná o Agile Manifesto obhajuje oceňování „pracovní softwaru přes úplnou dokumentaci“, které by mohly být interpretovány cynicky jako „Chceme, aby trávit veškerý svůj čas kódování. Nezapomeňte, že skuteční programátoři Nepište dokumentace.“

Průzkum mezi odborníky na softwarové inženýrství však odhalil, že dokumentace není v agilním vývoji v žádném případě považována za zbytečnou. Přesto se uznává, že při vývoji existují motivační problémy a že mohou být zapotřebí metody dokumentace přizpůsobené agilnímu vývoji (např. Prostřednictvím systémů reputace a gamifikace ).

Marketingová dokumentace

Pro mnoho aplikací je nutné mít nějaké propagační materiály, které povzbudí příležitostné pozorovatele, aby strávili více času učením se o produktu. Tato forma dokumentace má tři účely:

  1. Vzrušit potenciálního uživatele o produktu a vzbudit v něm touhu po větší angažovanosti s ním.
  2. Informovat je o tom, co přesně produkt dělá, aby jejich očekávání byla v souladu s tím, co dostanou.
  3. Vysvětlit pozici tohoto produktu s ohledem na jiné alternativy.

Viz také

Poznámky