Okamžik
Chování retence je vysvětleno v README, v referenčním dokumentu a na stránce webu. Tři popisy se liší. Dva z nich byly kdysi pravdivé. Na žádném není označeno, který.
Proč k tomu dochází
Napsat druhé vysvětlení je snazší než najít a propojit první, zejména když je první v dokumentu s jiným publikem. Každá kopie vzniká rozumně a od té doby se náklady na údržbu násobí, zatímco pozornost údržbě ne.
Proč to lepší model nevyřeší
Pracovník požádaný o aktualizaci dokumentace aktualizuje kopii, kterou mu ukázali. Nemůže vědět, že existují další dvě. Požádat jej, aby nejprve hledal duplikáty, je žádat inferenci o práci, kterou by odvození udělalo přesně.
Co to stojí
Čtenáři jednají podle zastaralých kopií. Přispěvatelé jednu aktualizují a jsou opraveni. A nahromaděná divergence činí každý jednotlivý dokument nedůvěryhodným, takže se lidé ptají člověka — což je cena, které se dokumentace měla vyhnout.
Co Majordomus dělá
Každý fakt má jeden kanonický domov a vše ostatní, co jej ukazuje, je projekce s kontrolou. Vrstva vlastní své dokumenty s rozsahem ve svých adresářích; politika vlastní pravidla; deklarace schopností vlastní rozhraní; plán vlastní stav. Web, referenční dokumenty a bootstrapy providerů se z toho generují a vygenerovaný soubor, který se liší od toho, co jeho zdroj produkuje, kontrolou neprojde. Kde by próza uváděla číslo, pravidlo je uvést příkaz, který jej počítá.
Před a po
before README.md "records are kept for 90 days"
docs/RETENTION.md "records are kept for 30 days"
site page "records are kept indefinitely"
after policy.yaml ledger.retention_max_lines: 5000
everything else generated from it, and drift-checkedCo nedělá
Nezjišťuje, že dva ručně psané odstavce říkají totéž. Odstraňuje potřebu druhého odstavce tím, že místa, která by jej držela, činí výstupy.