nimmo/nixos-config
nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 15 Pull requests Wiki Activity Actions
Page: 00 Documentation Standards
Pages
00 Documentation Map and Scope 00 Documentation Standards 00 Start Here and Governance 10 System Atlas 11 Fleet Overview 12 Host Inventory 13 Service Catalogue 14 Network and Access Topology 15 Storage and Data Map 16 Automation and Control Plane 20 Architecture Decisions 21 ADR 001 Electra Hardware Specialisations 22 ADR 002 Workload Placement 23 ADR 003 Network Exposure 23 Project Tracking 24 ADR 004 Engram Durable Agent Memory 24 Security Baseline 25 ADR 005 Auto Update Control Plane 26 ADR 006 Scoped Secret Files 30 Operations and Runbooks 31 Routine Fleet Operations 32 Safe Testing and Deployment 33 Host Provisioning 34 Monitoring and Service Investigation 35 Backup Verification and Partial Restore 36 Full Host Recovery 37 Electra Boot Trust Recovery 38 Secret Editing and Recipient Rotation 39 Auto Update Incident Response 39a Service Migration and Cutover 39b Wrapper Repository Packaging 40 Engineering Handbook 41 Repository Structure and Import Chain 42 Configuration Ownership Boundaries 43 Adding Packages and Flake Inputs 44 Adding a Module or Profile 45 Adding a Host 46 Adding or Migrating a Service 47 Testing and CI Contracts 48 Secrets Implementation Conventions 49 Documentation Maintenance 50 NixOS Learning Path 51 Guided Repository Tour 52 Nix Language Essentials 53 Declarative Configuration Store and Generations 54 Flakes and Inputs 55 NixOS Modules and Option Merging 56 SpecialArgs and Home Manager Argument Flow 57 Electra Specialisations Worked Example 58 Nix Troubleshooting Primer 90 Historical Material 91 Electra Secure Boot Hardening Record Home
3 00 Documentation Standards
Nimmo edited this page 2026-09-14 07:30:17 +01:00
Table of contents

Documentation Standards

  • Type: Policy
  • Status: Current
  • Scope: Repository wiki
  • Canonical sources: wiki rebuild issue #219
  • Last verified: Source commit 556df88494686003b1c4f20c8e0b99b5afc16a6e (2026-09-12)
  • Review triggers: Changes to wiki structure, maintenance workflow, page metadata, or Forgejo wiki behavior

One canonical purpose per page

Use page type to decide what a page owns:

Type Primary question
Reference What exists now?
Runbook How is it operated, repaired, or recovered?
ADR Why was a consequential choice made, and what follows from it?
Policy What is required, prohibited, or accepted?
Tutorial How should a learner understand or practise it?
Index Where is the relevant material?

A subject may need more than one page type. For example, secrets have a current topology, a recipient-rotation runbook, a scoped-secrets ADR, and a learning explanation. Cross-link those pages; do not make each repeat the other three.

Required metadata

Every substantive non-ADR page starts with:

> - **Type:** Reference | Runbook | Policy | Tutorial
> - **Status:** Current | Transitional | Superseded
> - **Scope:** Fleet, repository, host, service, or subsystem
> - **Canonical sources:** Exact repository paths or external authorities
> - **Last verified:** Source commit `<full commit>` (`YYYY-MM-DD`)
> - **Review triggers:** Concrete source or policy changes

Indexes use the same block with Type: Index. A page's verification statement applies only to that page. There is no wiki-wide claim that every page is current at one source commit.

An ADR instead records:

# ADR-NNN: Decision title

> - **Status:** Proposed | Accepted | Superseded
> - **Date:** YYYY-MM-DD
> - **Scope:** Subsystem or decision boundary
> - **Supersedes:** ADR or `None`
> - **Superseded by:** ADR or `None`

## Context
## Decision
## Consequences
## Alternatives considered
## References

Naming in the flat wiki namespace

  • Section indexes use decade prefixes: 10-System-Atlas, 30-Operations-and-Runbooks.
  • Pages within a section use its available numeric range: 11-Fleet-Inventory, 31-Safe-Deployment.
  • ADR titles retain a stable decision number even if the filename also carries a navigation prefix: 21-ADR-001-Electra-Hardware-Specialisations.
  • Use descriptive stable names. Never use export dates or source-snapshot prefixes in wiki page names.
  • Rename only when responsibility changes; ordinary content updates keep the same page name.

Linking

  • Use Forgejo wiki slugs for internal links, for example [System Atlas](10-System-Atlas).
  • Link to the canonical page rather than duplicating its content.
  • Link repository paths to the source browser where that materially helps the reader.
  • Do not create links to planned pages before those pages exist; list them as planned text instead.
  • During a migration, section indexes may link to legacy pages only with an explicit transitional warning; remove those links at cutover.

Reference page template

After the metadata block, include purpose, current state, relationships or inventory, boundaries, canonical source map, and known transitional state. Avoid large copied configuration blocks.

Runbook template

After the metadata block, include purpose, prerequisites, safety boundary, ordered procedure, success checks, rollback or recovery, troubleshooting, and canonical sources. Commands must be verified before the page is marked Current.

Policy template

After the metadata block, state the policy, rationale, required controls, exceptions, review/enforcement process, and related ADRs or runbooks.

Tutorial template

After the metadata block, state prerequisites, learning goal, explanation, guided example from this repository, exercises or checks, common mistakes, and authoritative upstream references. Prefer upstream Nix documentation for general-purpose reference material.

Review and transition rules

For the source-verification and publishing workflow, use Documentation Maintenance.

  • Treat retrieved memories, old wiki prose, README descriptions, and issue history as leads until verified against current authoritative sources.
  • Mark genuinely uncertain live state rather than inferring deployment from configuration alone.
  • A legacy page may remain reachable during migration, but its section index must say that it is transitional.
  • Remove a legacy page from the current tree only after its durable content has a destination and internal links have been updated.
  • Git history is the default archive. Keep a visible historical page only when it has continuing explanatory or rollback value.