Softwarová dokumentace - tištěné uživatelské příručky, on-line (online) dokumentace a text nápovědy popisující použití softwarového produktu [1] .
Dokument - prvek dokumentace: cílená informace určená pro konkrétní publikum, umístěná na konkrétním médiu (například v knize, na disku, na kartě rychlého odkazu) v daném formátu [1] .
Programová dokumentace - dokumenty obsahující v závislosti na účelu údaje potřebné pro vývoj, výrobu, provoz, údržbu programu nebo softwarového nástroje [2] .
Existují čtyři hlavní typy softwarové dokumentace:
Projektová dokumentace obvykle popisuje výrobek obecně. Aniž by popisoval, jak se něco bude používat, spíše odpovídá na otázku „proč to tak je“. Například v dokumentu návrhu může programátor popsat zdůvodnění, proč jsou datové struktury organizovány tak, jak jsou. Jsou popsány důvody, proč je třída navržena určitým způsobem, jsou zvýrazněny vzory a v některých případech jsou uvedeny i nápady, jak lze v budoucnu dosáhnout zlepšení. Nic z toho není v technické nebo uživatelské dokumentaci, ale pro projekt je to všechno opravdu důležité.
Při vytváření programu obvykle nestačí pouze kód . Měl by být poskytnut text popisující různé aspekty toho, co přesně kód dělá. Taková dokumentace je často zahrnuta přímo ve zdrojovém kódu nebo je s ním dodávána.
Taková dokumentace je vysoce technické povahy a primárně se používá k definování a popisu rozhraní API , datových struktur a algoritmů .
Často se při sestavování technické dokumentace používají automatizované nástroje - generátory dokumentace , jako je Doxygen , javadoc , NDoc a další. Své informace berou ze speciálně formátovaných komentářů ve zdrojovém kódu a vytvářejí nápovědu v nějakém formátu, jako je text nebo HTML .
Mnoho programátorů z různých důvodů zjistilo, že použití generátorů dokumentace a komentářů k dokumentaci je pohodlným nástrojem. Zejména při tomto přístupu je dokumentace součástí zdrojového kódu a stejné nástroje lze použít k sestavení programu a zároveň k sestavení dokumentace k němu. Usnadňuje také udržování aktuální dokumentace.
Na rozdíl od technické dokumentace, která se zaměřuje na kód a jak funguje, uživatelská dokumentace pouze popisuje, jak program používat.
Pokud je produktem softwarová knihovna , uživatelská dokumentace a dokumentace kódu se velmi přibližují, téměř ekvivalentní pojmy. Ale obecně tomu tak není.
Uživatelská dokumentace je obvykle uživatelská příručka , která popisuje jednotlivé funkce programu a také kroky, které je třeba při používání této funkce dodržet. Dobrá uživatelská dokumentace jde ještě dále a poskytuje pokyny, co dělat v případě problémů. Je velmi důležité, aby dokumentace nebyla zavádějící a aktuální. Vedení by mělo mít jasnou strukturu; velmi užitečné, pokud existuje průřezový index . Velký význam má také logická soudržnost a jednoduchost.
Existují tři přístupy k uspořádání uživatelské dokumentace. Úvodní příručka , která je nejužitečnější pro nové uživatele, vás provede řadou kroků k dokončení některých běžných úkolů. Pro pokročilé uživatele je vhodnější tematický přístup, kdy se každá kapitola manuálu zaměřuje na určité téma. V posledním, třetím přístupu jsou příkazy nebo úkoly uspořádány jako abecední reference – často dobře přijaté pokročilými uživateli, kteří dobře vědí, co hledají. Stížnosti uživatelů se obvykle týkají skutečnosti, že dokumentace pokrývá pouze jeden z těchto přístupů, a proto je vhodná pouze pro jednu třídu uživatelů.
V mnoha případech vývojáři softwarových produktů omezují sadu uživatelské dokumentace pouze na vestavěný systém nápovědy ( anglicky online help ), obsahující informace nápovědy o příkazech nebo položkách nabídky. Vzdělávání nových uživatelů a podpora vyvíjejících se uživatelů je ponechána na soukromých vydavatelích, kteří často vývojářům významně pomáhají.
U mnoha aplikací je potřeba mít vedle sebe propagační materiály, aby lidi zaujaly tím, že je na produkt upozorní. Tato forma dokumentace je určena pro:
Jednou z dobrých marketingových praktik je poskytnout slogan – jednoduchou chytlavou frázi, která ilustruje, co chceme uživateli sdělit, a zároveň popisuje pocit , který produkt vytváří.
Často se stává, že produktový box a další marketingové materiály dávají jasnější obrázek o možnostech a způsobech využití programu než cokoli jiného.
| Vývoj softwaru | |
|---|---|
| Proces |
|
Koncepty na vysoké úrovni | |
| Pokyny |
|
Vývojové metodiky | |
| Modelky |
|
| Pozoruhodné postavy |
|