Diff nástroje pro tech writery - co používám a proč

Technická dokumentace je věc, co se mění pořád. Každá verze API, každý nový feature, každý bug fix. A ty potřebuješ vědět co se změnilo, abys mohl aktualizovat docs.

S čím se potýkám

• API dokumentace - mění se s každou verzí backendu
• User manuály - nové featury, změny v UI
• Release notes - shrnutí všech změn
• Troubleshooting guides - nové edge cases
• Architektura - systémové změny

Všechno je "living document" a bez diffů bych se zbláznil.

Kdy sáhnu po diffu

Typické situace:

1. Developer aktualizoval endpoint - potřebuju vidět co se změnilo v parametrech
2. Product manager upravil spec - kde přesně udělal změny?
3. Reviewer mi vrátil draft - co navrhuje jinak?
4. Migration guide - co se změnilo od minulé verze?

Můj workflow pro API docs

U API dokumentace mám docela zajetý proces:

1. Sleduju změny v OpenAPI/Swagger specifikaci
2. Diffuju mezi verzemi
3. Z diffu generuju podklady pro changelog
4. Hledám breaking changes (ty vyžadují migration guide)

Když máš Git webhook, můžeš tohle částečně automatizovat.

Co používám

Pro Markdown dokumentaci:

• Git diff - klasika, funguje skvěle
• PorovnejText - když potřebuju rychle porovnat dva kusy textu

Pro API specs:

• Stoplight nebo SwaggerHub - mají built-in diffing
• Nebo exportuju jako JSON/YAML a diffuju tady

Pro spolupráci:

• Confluence/Notion - mají version history
• GitBook/ReadTheDocs - built-in diffing

Co jsem se naučil

Verzuj dokumentaci společně s produktem - když vyjde verze 2.0, dokumentace by měla mít stejný tag.

Taguj dokumenty - "Draft", "Client Review", "Final" pomáhá orientaci.

Udržuj changelog - i pro dokumentaci samotnou. Jednou se to hodí.

Archivuj staré verze - někdo může používat starší verzi produktu.

Spolupráce s vývojáři

Tohle je klíčové. Nastavili jsme si:

• Developer musí aktualizovat docs v PR (jinak neprojde review)
• Já koukám na code changes a ptám se "potřebuje tohle update v docs?"
• Máme issue tracking na "documentation debt"
• CI check varuje když docs nejsou aktuální

Není to dokonalé, ale funguje to líp než "někdy to doplníme".

Deprecated features

Tady je důležité:

1. Označ jasně že je to deprecated (a kdy to zmizí)
2. Ukaž alternativu - co použít místo toho
3. Nechej starou dokumentaci dostupnou
4. Komunikuj v release notes

---

Diff nástroje jsou pro tech writera nezbytnost. Bez nich bych trávil hodiny hledáním co se vlastně změnilo.

Sleduješ změny v Markdown dokumentaci? Hoď to do Markdown Diff a máš přehled.