Filozofie dokumentace¶

Dokumentace není výstup. Je to infrastruktura.

Výstup je něco, co jednou vytvoříte a předáte. Infrastruktura je něco, co udržujete, protože systém, který podporuje, bez ní nemůže fungovat. V okamžiku, kdy zacházíte s dokumentací jako s výstupem, jste se již rozhodli, že do šesti měsíců bude zastaralá a nikdo jí nebude věřit.

Tři otázky¶

Každý dokument, který buduji, začíná třemi otázkami.

Kdo přichází bez kontextu? Dokumentace není psána pro člověka, který již ví. Je psána pro člověka, který přichází bez zkušeností — nový člen týmu, externí přispěvatel, budoucí já ve 3 ráno, když se něco rozbije. Pokud dokument vyžaduje předchozí znalosti k pochopení, je neúplný.

Co je jediný zdroj pravdy? Každý fakt v dokumentačním systému má domov. Jeden domov. Pokud se měření objeví ve třech dokumentech, nakonec se objeví ve třech dokumentech se třemi různými hodnotami. Čtenář nemůže vědět, které je správné. Pisatel nemůže udržovat všechna tři. Jediným řešením je architektura: jedno místo, kde každý fakt žije, a všude jinde ho odkazuje.

Co se stane, když se změní? Dokumentační systém, který nelze udržovat, nebude udržován. Jednoduchost není lenost — je to předpoklad pro dlouhodobou užitnost. Každé strukturální rozhodnutí filtruji přes: co musí udělat člověk, který zdědí tento projekt za dva roky, aby ho aktualizoval?

Odkud to pochází¶

Ve roce 2001 jsem vedl technologický časopis. Redakční disciplína měsíčního časopisu se příliš neliší od disciplíny dobrého dokumentačního systému. Termíny, konzistence, verzování, rozdíl mezi tím, co je přesné, a tím, co je užitečné. Přinesl jsem to vše do technické dokumentace, aniž bych věděl, že to dělám.

O dvacet pět let později jsem postup vědomě aplikoval na libdrone — open hardware platformu, která potřebovala dokumentaci dostatečně dobrou, aby schopný cizinec mohl hardware reprodukovat bez jediného kontaktu s autorem. Toto omezení je vyčišťující. Když musí dokumentace fungovat bez vás, rychle se naučíte, co chybí.

Co jsem se naučil¶

Architektura je ta práce. Psaní je sekundární. Dobře strukturovaný dokument s průměrnou prózou je užitečný. Krásně napsaný dokument bez struktury je šum. Každá hodina strávená navrhováním architektury před psaním se vyplatí mnohonásobně při údržbě.

Délka není kvalita. Nejlepší technická dokumentace, kterou jsem četl, je hustá a krátká. Každá věta si zaslouží své místo. Nejhorší je dlouhá, protože nikdo neudělal těžká redakční rozhodnutí o tom, co vyškrtnout.

Čtenář nejste vy. Vy systém znáte. Čtenář ne. Každá zkratka, každý implicitní předpoklad, každý termín použitý bez definice — to jsou daně, které čtenář platí. Dobrá dokumentace minimalizuje daň.

Údržba je nejtěžší část. Napsat první verzi je uspokojivé. Udržovat ji v průběhu vývoje systému je neatraktivní a nezbytné. Dokumentace, která není udržována, se stává aktivně škodlivou — popisuje něco, co již neexistuje, a zavádí lidi, kteří se na ni spoléhají.