Šablona dokumentace softwaru s vyplněným příkladem
Šablona dokumentace softwaru shrne na jedné stránce, co o aplikaci potřebuje vědět vývojář, podpora i zákazník. Body vyplníte nebo odkážete na hotový dokument.
Shrnutí a kontext
Dokumentace se obvykle píše dvakrát: na začátku projektu a den před předáním. Níže najdete šablonu dokumentace softwaru ke zkopírování a vyplněný příklad. Šablona nenutí nic přepisovat, u většiny bodů stačí odkaz na místo, kde dokument už je.
1. K čemu je šablona dokumentace
Dokumentace aplikace většinou existuje, jen po kouscích. README je v repozitáři, zadání v Confluence, postup nasazení v hlavě jednoho kolegy a poznámky k vydání v pull requestech. Kdo s aplikací začíná, neví, kde hledat, a podpora často ani nezjistí, jakou verzi má zákazník nasazenou.
Šablona funguje jako rozcestník. Na jedné stránce projde všechny oblasti a u každé řekne, kde je dokument a kdo za něj odpovídá. Proč dokumentovat právě tyhle oblasti, vysvětluje článek Co dokumentovat v softwarovém projektu. Tady je šablona, kterou rovnou vyplníte.
2. Šablona dokumentace softwaru
Šablona má sedm částí. Co nevíte, nechte prázdné nebo napište „nevíme“, je to užitečnější informace než vymyšlený údaj. Pro podrobnou dokumentaci architektury se hodí šablona arc42, pro uživatelskou dokumentaci rozdělení podle Diátaxis na výukové návody, postupy, referenci a vysvětlení.
Přístupové údaje, API klíče ani připojovací řetězce do šablony nepište. Uveďte jen odkaz na správce hesel nebo trezor tajných klíčů, kde je najde ten, kdo k nim má mít přístup.
# <Název aplikace>: dokumentace
## 1. Přehled
- Účel: jedna věta, k čemu aplikace slouží
- Uživatelé: kdo s aplikací pracuje
- Odpovědná osoba:
- Licence:
- Aktuální verze: <číslo>, v aplikaci ji najdete <kde>
## 2. Vznik a požadavky
- Zadání a specifikace: <odkaz>
- Analýzy a zápisy z jednání: <odkaz>
- Architektonická rozhodnutí: <odkaz>
- AI projekt nebo prompty, pokud aplikace vznikla s AI: <odkaz>
## 3. Zdrojový kód a technická dokumentace
- Repozitář: <odkaz>
- Spuštění projektu lokálně: <odkaz na README>
- Architektura a datový model: <odkaz>
- Popis API (OpenAPI): <odkaz>
## 4. Prostředí a nasazení
| Prostředí | URL | Hosting | Verze |
| --- | --- | --- | --- |
| Produkce | | | |
| Test | | | |
- Postup nasazení a CI/CD pipeline: <odkaz>
- Poznámky k vydání: <odkaz>
- Služby třetích stran: <seznam s odkazy>
## 5. Provoz
- Monitoring a logy: <odkaz>
- Hlášení chyb a požadavků: <odkaz>
- Zálohy a obnova: <odkaz>
- Postup při výpadku: <odkaz>
- Kontakt na podporu:
## 6. Uživatelská dokumentace
- Uživatelský manuál: <odkaz>
- Návody, videa, časté otázky: <odkaz>
## 7. Právo a licence
- Podmínky použití a ochrana osobních údajů: <odkaz>
- Smlouvy a SLA: <odkaz>
- Licence použitých komponent: <odkaz>3. Vyplněný příklad
Takhle může vyplněná šablona vypadat u menší interní aplikace. Většina řádků je odkaz, vlastní text má jen přehled a tabulka prostředí.
# Rezervace zasedaček: dokumentace
## 1. Přehled
- Účel: rezervace zasedacích místností v kanceláři
- Uživatelé: všichni zaměstnanci, správu místností má recepce
- Odpovědná osoba: vedoucí interního vývoje
- Licence: interní, bez distribuce
- Aktuální verze: 1.8.2, v aplikaci ji najdete v patičce
## 2. Vznik a požadavky
- Zadání a specifikace: Confluence, stránka „Rezervace – zadání“
- Architektonická rozhodnutí: docs/adr/ v repozitáři
## 3. Zdrojový kód a technická dokumentace
- Repozitář: github.com/acme/room-booking
- Spuštění projektu lokálně: README.md v repozitáři
- Popis API (OpenAPI): /api/docs na testovacím prostředí
## 4. Prostředí a nasazení
| Prostředí | URL | Hosting | Verze |
| --- | --- | --- | --- |
| Produkce | rooms.acme.example | Azure App Service | 1.8.2 |
| Test | rooms-test.acme.example | Azure App Service | 1.9.0-rc.1 |
- Postup nasazení a CI/CD pipeline: GitHub Actions, workflow deploy.yml
- Poznámky k vydání: GitHub Releases
- Služby třetích stran: Microsoft 365 (kalendáře místností)
## 5. Provoz
- Monitoring a logy: Azure Application Insights
- Hlášení chyb a požadavků: Jira, projekt ROOMS
- Zálohy a obnova: nevíme, doplní provoz
- Kontakt na podporu: [email protected]
## 6. Uživatelská dokumentace
- Uživatelský manuál: intranet, stránka „Jak rezervovat zasedačku“4. Jak šablonu vyplnit, aby nezastarala
Zastaralá dokumentace je horší než chybějící, protože jí lidé věří. Šablona proto obsahuje co nejméně opsaného textu a co nejvíc odkazů na zdroj, který se udržuje sám.
5. Dokumentace mobilní aplikace
Mobilní aplikace potřebuje navíc údaje, které u webové aplikace nejsou: účty v obchodech, podpisové klíče a certifikáty, které po čase vyprší. Kdo je nezná, nevydá ani opravu chyby a obvykle to zjistí ve chvíli, kdy oprava spěchá.
Do šablony proto přidejte osmou část. Hesla a klíče do ní nepatří, jen informace, kde jsou uložené a kdo k nim má přístup.
## 8. Mobilní aplikace
- Obchody: App Store Connect (tým Acme), Google Play Console (účet Acme)
- Identifikátor aplikace: com.acme.roombooking (iOS i Android)
- Podpisové klíče a certifikáty: ve správci hesel, složka „Mobile – podpisy“, přístup má vedoucí vývoje
- Číslování: verze 1.8.2, číslo sestavení zvyšuje CI při každém nahrání do obchodu
- Notifikace: APNs klíč a Firebase projekt room-booking-prod
- Testovací distribuce: TestFlight, interní testování v Google Play
- Podporované systémy: iOS 16 a novější, Android 8.0 a novější
- Zásady ochrany osobních údajů pro obchody: <odkaz>6. Kde má být šablona dokumentace
Soubor v repozitáři stačí vývojářům. Jenže podpora, konzultant nebo zákazník k repozitáři přístup obvykle nemají, takže se ke stejným informacím dostávají přes dotazy na vývojáře. Při předání aplikace navíc soubor v repozitáři snadno přehlédnou.
V AboutTheApp má každá část šablony svou kategorii odkazů. Odkazy připojíte k aplikaci, u každého zvolíte, jestli je veřejný nebo privátní, a na About page se zobrazí seřazené podle kategorií. Verze a prostředí z části 4 nevedete jako odkazy, ale v katalogu verzí a v nasazeních u jednotlivých zákazníků.
| Část šablony | Kategorie v AboutTheApp |
|---|---|
| 1. Přehled | Název, popis, autor a licence produktu, verze z katalogu verzí |
| 2. Vznik a požadavky | Analýzy a plánování, AI |
| 3. Zdrojový kód a technická dokumentace | Zdrojový kód a architektura, API |
| 4. Prostředí a nasazení | Nasazení u zákazníků, DevOps a infrastruktura |
| 5. Provoz | Monitoring a kvalita, Sledování úkolů, Podpora, Zabezpečení |
| 6. Uživatelská dokumentace | Dokumentace |
| 7. Právo a licence | Právo a vztahy, Komponenty a licence |
| 8. Mobilní aplikace | DevOps a infrastruktura, Zabezpečení, Právo a vztahy |
Časté otázky
Co má obsahovat dokumentace softwaru?
Přehled aplikace, podklady k jejímu vzniku, technickou dokumentaci ke zdrojovému kódu a API, přehled prostředí a nasazených verzí, provozní postupy, uživatelskou dokumentaci a právní dokumenty. Ne všechno musí být v jednom souboru, stačí na každou část odkázat.
Jak podrobná má být dokumentace softwaru?
Tak podrobná, aby se v aplikaci zorientoval nový člověk bez dotazu na autora. U menší aplikace stačí vyplněná šablona s odkazy na jednu stránku. Podrobnosti patří do dokumentů, na které šablona odkazuje.
Existuje standard pro dokumentaci softwaru?
Jeden závazný standard neexistuje. Pro architekturu se často používá šablona arc42, pro uživatelskou dokumentaci rozdělení Diátaxis a ve formálních projektech normy ISO/IEC/IEEE. Pro běžný projekt stačí jednotná šablona, kterou tým opravdu vyplňuje.
Kdo má udržovat dokumentaci softwaru?
Ten, kdo danou věc mění. Vývojář upraví technickou část při změně kódu, provoz při změně prostředí a produktový vlastník u uživatelské dokumentace. Šablona s odpovědnou osobou u každé části pomůže, aby úprava nezůstala na nikom.
Co má obsahovat technická dokumentace mobilní aplikace?
Totéž co u jiných aplikací a navíc účty v App Store Connect a Google Play Console, identifikátor aplikace, místo uložení podpisových klíčů a certifikátů, pravidla pro číslování verzí a sestavení, nastavení notifikací, testovací distribuci a podporované verze systémů.
Můžu dokumentaci nechat v Confluence nebo Notionu a mít ji přesto na jednom místě?
Ano. Dokumenty mohou zůstat tam, kde je tým píše, potřebujete jen jedno místo, které na ně odkazuje. V AboutTheApp připojíte odkazy k aplikaci podle kategorií a zobrazíte je na About page i přímo v aplikaci v About boxu.
Ve zkratce
Vyplněná šablona nemusí obsahovat celou dokumentaci. Stačí, když u každé oblasti řekne, kde dokument je a kdo za něj odpovídá.
Chcete mít vyplněnou šablonu u aplikace?
Založte si zdarma aplikaci v AboutTheApp a připojte k ní odkazy ze všech sedmi částí šablony.