Docs Principles and voice
Principles and voice
What the site and repository value — and the writing voice the whole site holds to.
These are the standing guardrails for the site and the repository behind it.
What the site should feel like
- Fast and quiet. A static site that loads instantly, reads well on a phone, and respects light and dark. No heavy frameworks, no tracking, no clutter.
- Always current. The projects list, the updates feed, and the feeds are generated, so they do not drift. Adding a project is a single edit to one registry.
- Professional and clear. A plain, direct voice — no gimmicks and no cutesy filler.
The documentation voice
The site is written about the projects and the work — not in the owner’s first person, and not as a personal brand. Fairy Fox is referred to by name only for attribution; the site documents and indexes the work rather than boasting about it. Mentioning and describing what the work does is expected; glorifying it is not. This neutral voice is what keeps the hub readable as documentation.
What the repository should feel like
- Self-documenting. A newcomer — a person or an AI assistant — can get oriented from the README, to the entry-point file, to the notes, with nothing trapped in one person’s head. The notes are a living document, kept current by default.
- Low-risk git. A clean, faithful, linear history: a working branch for development, and a deployable branch that only moves by fast-forward and is never rewritten once pushed. See the git workflow.
- One source of truth per fact. The version number lives only in
VERSION; the project list only in its registry; the shared standards only in the hub. Nothing is duplicated — it is linked.
Cross-project discipline
- Git only, one direction at a time. Projects communicate with the hub solely through git: the hub reads projects, and projects read the hub. No submodules, no live dependency, no build-time coupling.
- Pull on explicit request, never automatically. This is what prevents a loop where one repository’s update triggers another’s.
- The hub is the source of shared standards; projects own their own content. A convention is promoted up to the hub when it is reusable, and project-specific detail stays down in the project. See cross-project sync.