Dokumentace, kterou nikdo nečte, je zbytečná. Tady je jak psát tu užitečnou.
Typy dokumentace¶
- Tutorial — učí (krok za krokem)
- How-to guide — řeší problém
- Reference — technický detail
- Explanation — vysvětluje koncepty
Principy¶
- Pište pro čtenáře, ne pro sebe
- Konkrétní příklady > abstraktní vysvětlení
- Krátké věty, krátké odstavce
- Kód, který funguje (ne pseudokód)
- Aktualizujte — zastaralá dokumentace je horší než žádná
Struktura¶
- Proč — motivace a kontext
- Co — co to dělá / řeší
- Jak — krok za krokem s příklady
- Reference — API, config, parametry
- Troubleshooting — známé problémy
Nástroje¶
- Markdown + Git — jednoduché, verzované
- MkDocs / Docusaurus — static site generátory
- Notion / Confluence — pro interní docs
- OpenAPI/Swagger — pro API dokumentaci
Docs as Code¶
Dokumentaci verzujte v Gitu vedle kódu. Review v PR. CI/CD pro publikaci. Kód a docs se vyvíjí společně.
Test¶
Dejte docs novému vývojáři. Zvládne se z nich rozběhnout? Pokud ne, vylepšete.
dokumentacewritingbest practices