Single source of truth¶

The most important file in the libdrone documentation is not the specification or the build guide. It's 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 — specification, hardware document, build guide, SDK, shopping list — references variable names, not values. When something changes, you change one file. The rest updates.

This isn't a new idea; it's how good engineering documentation has always worked. What's unusual is applying it, with editorial rigour, to a personal open hardware project with a forty-document stack.

Why most documentation doesn't do this¶

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

You know the wheelbase is 330 mm, so you write 330 mm. Done. Then the design changes to 340 mm. You search for 330, find seven instances, change six, miss one. Six months later someone builds to the wrong dimension and can't tell you why it doesn't fit.

The variables file forces you to decide, at the start, what the canonical values are and where they live. It's architecture work — less exciting than prose, and it prevents a category of error that compounds badly over time.

How to implement it in MkDocs¶

The variables file is a plain markdown document: human-readable, version-controlled, authoritative. Other documents reference it in prose:

The arm length is {{ arm_length }}mm, giving a wheelbase of {{ wheelbase }}mm.

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

plugins:
  - macros

That's the architecture. Everything else is filling it in.

The editorial principle behind it¶

Single source of truth is not a technical pattern. It's an editorial commitment: accuracy matters more than convenience, and the person reading this document six months from now deserves the same quality as the person reading it today. In print there is no version two — that discipline is extreme, but the principle applies everywhere.