Jak psát README a dokumentaci, kterou lidé opravdu čtou

Dokumentace má jediný cíl: aby další člověk (včetně vás za rok) dokázal projekt pochopit, spustit a změnit bez toho, aby se musel ptát autora. Nemusí být dlouhá. Musí být správná, aktuální a na správném místě.

Čtyři druhy dokumentace

Užitečné je rozlišovat dokumentaci podle účelu (tzv. rámec Diátaxis):

Druh	Otázka čtenáře	Příklad
Tutoriál	„Jak začít?“	Krok za krokem první spuštění
Návod (how-to)	„Jak udělat X?“	Jak přidat novou platební metodu
Reference	„Jaké jsou parametry?“	Popis API, konfiguračních klíčů
Vysvětlení	„Proč to tak je?“	Architektura, rozhodnutí

Nejčastější chyba je míchání: reference plná výkladu nebo tutoriál, který odbíhá k výjimkám.

README: struktura, která funguje

README čte člověk, který o projektu nic neví. Pořadí sekcí podle toho, co potřebuje nejdřív:

# Název projektu

Jedna až dvě věty: co projekt dělá a pro koho.

## Rychlý start

```bash
git clone https://github.com/firma/projekt.git
cd projekt
cp .env.example .env
docker compose up
```

Aplikace poběží na http://localhost:8000.

## Požadavky
- Python 3.12+
- PostgreSQL 16

## Konfigurace
| Proměnná | Povinná | Popis |
|---|---|---|
| `DATABASE_URL` | ano | Připojení k PostgreSQL |
| `SMTP_HOST` | ne | Server pro odesílání e-mailů |

## Vývoj
- Testy: `pytest`
- Linter: `ruff check .`
- Migrace: `python manage.py migrate`

## Nasazení
Odkaz na docs/deploy.md

## Licence
MIT

Pravidla pro README

• Rychlý start musí fungovat. Vyzkoušejte ho v čistém prostředí (nový kontejner, čerstvý klon). Chybějící krok je nejčastější vada README.
• Příkazy jako bloky kódu, které jdou zkopírovat. Bez $ na začátku, pokud nejde o ukázku výstupu.
• Konkrétní verze, ne „nějaký novější Python“.
• Dlouhé věci odkažte do složky docs/. README má být vstupní brána, ne kniha.

Dokumentace v kódu

Docstringy a JSDoc

Dokumentujte veřejné rozhraní – funkce, třídy a moduly, které používají ostatní:

def calculate_vat(amount: Decimal, rate: Decimal) -> Decimal:
    """Vypočítá DPH z částky bez daně.

    Args:
        amount: Částka bez DPH v Kč.
        rate: Sazba jako desetinné číslo, např. Decimal("0.21").

    Returns:
        DPH zaokrouhlená na haléře (ROUND_HALF_UP).

    Raises:
        ValueError: Pokud je amount záporná.
    """

/**
 * Vypočítá DPH z částky bez daně.
 * @param {number} amount - Částka bez DPH v Kč.
 * @param {number} rate - Sazba, např. 0.21.
 * @returns {number} DPH zaokrouhlená na haléře.
 * @throws {RangeError} Pokud je amount záporná.
 */
function calculateVat(amount, rate) { /* … */ }

Z docstringů lze generovat referenční dokumentaci (Sphinx, MkDocs s mkdocstrings, TypeDoc) a editory je zobrazují v nápovědě.

Typy jsou dokumentace

Typové anotace v Pythonu nebo TypeScript řeknou o funkci víc než odstavec textu a na rozdíl od komentáře je hlídá nástroj (mypy, tsc).

Komentáře vysvětlují „proč“

Kód říká co. Komentář má říct to, co z kódu nevyčtete: důvod, omezení, odkaz na ticket.

ADR: záznamy o architektonických rozhodnutích

Za rok nikdo nebude vědět, proč jste zvolili Redis místo RabbitMQ. Architecture Decision Record je krátký soubor v docs/adr/:

# 0007: Fronta úloh přes Redis (RQ)

Stav: přijato · Datum: 2026-03-02

## Kontext
Potřebujeme asynchronně odesílat e-maily a generovat PDF. Redis už
používáme pro cache.

## Rozhodnutí
Použijeme RQ nad existujícím Redisem.

## Důsledky
+ Žádná nová infrastruktura.
- Méně pokročilé směrování než RabbitMQ; při potřebě priorit znovu zvážit.

ADR se nemaže ani nepřepisuje. Když se rozhodnutí změní, vznikne nový záznam, který ten starý nahrazuje.

CHANGELOG

Uživatelé knihovny nebo API potřebují vědět, co se změnilo. Osvědčený formát je Keep a Changelog:

## [2.1.0] - 2026-09-14
### Added
- Export do CSV.
### Fixed
- Chybný součet při prázdném měsíci.
### Deprecated
- Parametr `format=xls`, bude odstraněn ve verzi 3.0.

Spolu se sémantickým verzováním (MAJOR.MINOR.PATCH) dává čtenáři jasno, zda je aktualizace bezpečná.

Jak dokumentaci udržet aktuální

Zastaralá dokumentace je horší než žádná – čtenář jí věří.

• Dokumentace žije v repozitáři vedle kódu, ne na wiki, na kterou nikdo nechodí. Změna kódu a dokumentace pak jde v jednom pull requestu.
• Checklist v šabloně PR: „Aktualizoval jsem dokumentaci?“
• Testujte příklady. V Pythonu python -m doctest nebo pytest --doctest-modules spustí příklady v docstringech.
• Kontrolujte odkazy v CI (např. nástroj lychee).
• Generujte, co jde: OpenAPI specifikaci z kódu API, referenci z docstringů.

AI jako pomocník při psaní dokumentace

AI je výborná na první verzi: z kódu vygeneruje docstringy, z repozitáře kostru README, z diffu záznam do CHANGELOGu. Vždy ale zkontrolujte fakta – AI ráda doplní příkaz nebo konfigurační klíč, který v projektu neexistuje. „Proč“ (kontext rozhodnutí) musíte dodat vy, ten v kódu není.

V ColdHost AI můžete nahrát projekt jako ZIP nebo ho importovat z GitHubu a požádat o návrh README podle skutečných souborů projektu.