Jediný zdroj pravdy¶

Nejdůležitější soubor v dokumentaci libdrone není hlavní specifikace. Není to návod k sestavení. Je to markdown soubor nazvaný Variables, který neobsahuje nic než názvy a čísla.

markdown arm_length: 150 wheelbase: 330 motor_mount_hole_spacing: 16 ...

Každý jiný dokument ve stacku — hlavní specifikace, hardwarový dokument, návod k sestavení, Payload SDK, nákupní seznam — odkazuje na názvy proměnných, ne na hodnoty. Když se něco změní, změníte jeden soubor. Zbytek se aktualizuje.

Toto není nová myšlenka. Takto vždy fungovala dobrá inženýrská dokumentace. Co je nové, je aplikovat to na osobní open hardware projekt se stackem čtyřiceti dokumentů, vynucené s přísností někoho, kdo dříve vedl časopis.

Proč to většina dokumentace nedělá¶

Protože je těžší nastavit než jen napsat číslo.

První návrh jakéhokoli dokumentu jde po cestě nejmenšího odporu. Víte, že rozvor je 330 mm. Napíšete 330 mm. Je to v dokumentu. Hotovo.

Pak se design změní. Rozvor je nyní 340 mm. Vyhledáte v dokumentu 330. Najdete sedm výskytů. Změníte šest. Jeden vám unikne. O šest měsíců později někdo staví podle špatného rozměru a nemůže vám říci, proč to nepasuje.

Disciplína souboru proměnných vás nutí rozhodnout, na začátku každého dokumentačního projektu, jaké jsou kanonické hodnoty a kde žijí. To je architektonická práce. Je méně vzrušující než psaní prózy. Zabraňuje kategorii chyb, které se v průběhu času špatně kumulují.

Jak to implementovat v MkDocs¶

V dokumentačním stacku libdrone je soubor proměnných prostý markdown dokument v adresáři reference/. Je čitelný člověkem, verzovaný a autoritativní zdroj pro každé měření.

Ostatní dokumenty ho odkazují v textu — například: Délka ramene je {{ arm_length }}mm, což dává rozvor {{ wheelbase }}mm.

S MkDocs pluginem macros se tyto reference vyřeší při buildu. Publikovaná dokumentace vždy odráží aktuální soubor proměnných. Zdrojové soubory obsahují názvy proměnných, ne hodnoty.

plugins:
  - macros

Toto je architektura. Vše ostatní je ji naplnit.

Redakční princip za tím¶

Jediný zdroj pravdy není technický vzor. Je to redakční závazek. Znamená to rozhodnout se, že přesnost je důležitější než pohodlí, a že člověk, který tento dokument čte za šest měsíců, si zaslouží stejnou kvalitu jako ten, kdo ho čte dnes.

Toto jsem se naučil vedením časopisu. V tisku neexistuje verze dvě. Redakční rozhodnutí uděláte správně napoprvé, nebo příští měsíc tisknete opravu. Disciplína tiskové publikace je extrémní, ale princip platí všude: každý fakt má jedno autoritativní místo a toto místo je udržováno.