Docs standard

Updated: 2026-09-29T12:53:41Z · Site standard for human-readable guides

Product law is standing for every article and IA change. Operator mirror: PRODUCT-LAW.md (also under Dispatch portfolio/docs/). This page summarizes that law for the live site — Title → Summary chrome, nesting under Projects/Docs, banned jargon, screenshots, hook-first. Related: ARTICLE-FORMAT.md, HOWTO-ADD-A-PROJECT.md.

Product law (summary)

  1. IA — Primary: Home | About | Projects | Docs | Self-hosted git | Skills | Contact. Write-ups nest under Projects and/or Docs (not top-level equals to Home). In-article TOC = #step-N anchors only — never a second site menu.
  2. Chrome — Open with Title + Summary / purpose only; no front-matter chip soup.
  3. Shape — Stepped guides; TOC required; hook in the first 1–2 sentences.
  4. Screenshots — Console/Build; blur secrets; figure tied to its step.
  5. Voice — Owner style + professional overlay; prefer prove / cut / gate / scrub / refuse / ship / break / fix / catch. Ban failure mode(s), fluff blast radius, empty leverage / hero.
  6. Site chrome — Home H1 = Data Center Network Engineer · GPU Host Deploy (nav label Home).

Open (quiet)

The write-up open is only:

  1. Title — page H1 / post_title (useful; never decorative “Hero”)
  2. Summary / purpose — one or two short sentences (hook first)

Then body: in-page TOC → steps → close. Do not put a heavy front-matter callout or chip soup at the top (stack / outcome / clone / label / screenshots / reading_time). Those may live lightly as authoring metadata, or as a short end note — not a noisy header block.

Voice

Write like the owner: plain, human, a little dry humor — then put a professional business overlay on top. Prefer weighted verbs: prove, cut, gate, scrub, refuse, ship, break, fix, catch. One smidge of sarcasm when a bad default deserves it. No buzzword fog, no invented production expertise.

Ban list (never as decoration): failure mode(s), fluff blast radius, empty leverage, empty hero / decorative Hero headings.

Authoring metadata (not page chrome)

  • title — short, outcome-oriented
  • summary — one or two sentences
  • stack — tools actually used
  • outcome — employer-neutral result
  • clone — optional public scrubbed sample URL
  • label — lab | production-theme | transferable
  • screenshots — console | build | none
  • reading_time — approximate (optional; never a top chip)

In-page TOC (required)

Every article longer than about three steps needs an in-page table of contents with jump anchors (#step-1-…). Style it as “On this page” inside the article — not as chrome that fights the header nav.

Segmented by steps

  1. Open — Title + Summary / purpose only
  2. TOC — in-page anchors
  3. Step N — verb phrase — short prose, commands, optional one screenshot
  4. Close — Outcome, optional Clone, optional “What I would do differently”; optional light meta only at the end

Screenshots (Console / Build)

  • Agent Console — operator UI, job/inbox, deploy confirmations (public-safe)
  • Build — lab/build captures and scrubbed before/after panels
  • Blur private IPs, tokens, emails, customer names, finance, WireGuard, identifying hostnames
  • Caption + id="fig-step-N"; nest under the step in the TOC; no orphan gallery at the bottom
  • Filename: step-N-slug-console.png or -build.png

Code and diagrams

Fenced code with language tags. Placeholders instead of private addressing. Mermaid/ASCII under Diagram; mark VXLAN/EVPN practice as lab.

Examples on this site

How to add a project

  1. Draft under Product law (Title + Summary → steps + TOC + screenshot plan).
  2. Create/update a WP page as a child of Projects (write-ups) or Docs (format demos); nest in Primary menu; card from Projects.
  3. Optional scrubbed bare repo under /git/ with landing index.html.
  4. Run the ship checklist in the markdown howto.
git clone https://www.portfolio.btcbrewery.com/git/<sample>.git