Single source of truth¶

The most important file in the libdrone documentation is not the master specification. It is not the build guide. It is a markdown file called Variables that contains nothing but names and numbers.

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

Every other document in the stack — master spec, hardware document, build guide, payload SDK, shopping list — references variable names, not values. When something changes, you change one file. The rest updates.

This is not a new idea. It is how good engineering documentation has always worked. What is new is applying it to a personal open hardware project with a forty-document stack, enforced with the rigour of someone who used to run a publication.

Why most documentation does not do this¶

Because it is harder to set up than to just write the number down.

The first draft of any document takes the path of least resistance. You know the wheelbase is 330mm. You write 330mm. It is in the document. Done.

Then the design changes. The wheelbase is now 340mm. You search the document for 330. You find seven instances. You change six. You miss one. Six months later someone builds to the wrong dimension and cannot tell you why it does not fit.

The variables file discipline forces you to decide, at the start of every documentation project, what the canonical values are and where they live. This is architecture work. It is less exciting than writing prose. It prevents a category of error that compounds badly over time.

How to implement it in MkDocs¶

In the libdrone documentation stack, the variables file is a plain markdown document in the reference/ directory. It is human-readable, version-controlled, and the authoritative source for every measurement.

Other documents reference it in the prose — for example: The arm length is {{ arm_length }}mm, giving a wheelbase of {{ wheelbase }}mm.

With the MkDocs macros plugin, these references resolve at build time. The published documentation always reflects the current variables file. The source files contain variable names, not values.

plugins:
  - macros

This is the architecture. Everything else is filling it in.

The editorial principle behind it¶

Single source of truth is not a technical pattern. It is an editorial commitment. It means deciding that accuracy matters more than convenience, and that the person who reads this document six months from now deserves the same quality as the person who reads it today.

I learned this running a magazine. In print, there is no version two. You make the editorial decision correctly the first time or you print a correction next month. The discipline of print publication is extreme, but the principle applies everywhere: every fact has one authoritative home, and that home is maintained.