Skip to content

Style Guide

Home / Style Guide

Guidelines for writing and maintaining these docs.

Every page (except Home) starts with a breadcrumb path showing where the page sits in the docs hierarchy. The breadcrumb goes immediately after the H1 heading, formatted as italic text with slashes between levels. Each ancestor is a link; the current page is plain text.

Format:

# Page Title

*[Home](../index.md) / [Section](index.md) / Page Title*

Example from a deeply nested page:

# Data Ingestion

*[Home](../../index.md) / [System Design](../index.md) / [CAM Pipeline](overview.md) / Data Ingestion*

Use relative paths for all links.

Avoid linking between documentation pages beyond breadcrumbs and index pages. The sidebar navigation and search are sufficient for readers to find related content.

Allowed:

  • Breadcrumbs (required on all pages except Home)
  • Index pages listing their child pages
  • Curated cross-section pointer links — a section index may link to a small, deliberate set of pages in another section when that's where the canonical content lives (e.g. a "Design Records" list in System Design pointing to dated design docs in the Engineering Log, or a single "see the … overview" pointer). Keep these intentional and few.
  • Links to external resources (vendor docs, GitHub repos, etc.)

Avoid:

  • "Related Pages", "See Also", or "References (Internal)" sections
  • Scattered inline cross-references between body paragraphs of pages in different sections
  • Duplicated navigation that mirrors the sidebar

Content Longevity

Write for a shelf life of one to two years. These docs should describe how the system works, what we've decided, and why — not what's happening this month.

Include:

  • Architecture and design decisions
  • Processes, workflows, and principles
  • Equipment specs, tool libraries, material choices
  • Organizational structure and role definitions

Avoid:

  • Specific dates and deadlines ("launch in July 2026")
  • Headcounts or funding figures that change quarterly
  • Sprint-level plans or short-term milestones
  • Status updates that belong in a project tracker

If something is genuinely time-bound, either frame it in relative terms ("initially", "at scale") or put it in a clearly marked section so it's easy to update or remove later.

Engineering Log Document Types

Every Engineering Log entry gets a short type tag that describes what kind of document it is. This tag appears in two places:

  • Nav titles — lowercase, after the date prefix: "2026-03-14 survey — CNC Simulation Landscape"
  • Index tables — Title Case in a Type column: | Mar 14 | Survey | CNC Simulation Landscape |
Tag Use for
survey Research, landscape analysis, vendor evaluation
design Architecture, system design, implementation plans (includes requirements docs)
scope Workstream/project scoping, goals, boundaries
guide Setup guides, how-tos, operational procedures

Add new tags as needed (e.g. rfc, postmortem, decision). Keep tags short — one word when possible.