Skip to content
NutsNews chestnut logoNutsNews Wiki

Simple guide · Contributing

Page status: Active

Documentation Style Guide

How to author equivalent, safe, and accessible Simple and Technical NutsNews Wiki articles.

Visual overview

Primary diagram

System map

A new or changed canonical Technical source is reconciled with its Simple mirror, Technical mirror, accessible diagram, metadata, links, images, and History placement. Human approval follows the complete review, and any stale change returns the bundle to review before validation and delivery.

Render the repository-owned system map when you need it.

Diagram is not rendered yet.

View as text
Documentation Style Guide

A new or changed canonical Technical source is reconciled with its Simple mirror, Technical mirror, accessible diagram, metadata, links, images, and History placement. Human approval follows the complete review, and any stale change returns the bundle to review before validation and delivery.

---
title: Documentation style guide content workflow
---

flowchart TB
  accTitle: Documentation Style Guide
  accDescr {
    A new or changed canonical Technical source is reconciled with its Simple mirror, Technical mirror, accessible diagram, metadata, links, images, and History placement. Human approval follows the complete review, and any stale change returns the bundle to review before validation and delivery.
  }
  request["New or changed canonical source"] --> scaffold{"New document?"}
  scaffold -->|Yes| newdoc["Run docs:new, then docs:prepare --force"]
  scaffold -->|No| update["Update the existing source"]
  newdoc --> bundle["Reconcile Simple mirror, Technical mirror, and diagram"]
  update --> bundle
  bundle --> safety["Preserve facts, commands, cautions, verification, and rollback"]
  safety --> assets["Check metadata, related links, images, accessibility, and History"]
  assets --> review["Human reviews the complete current bundle"]
  review --> approve["Run docs:approve"]
  approve --> validate["Run complete content, link, Mermaid, route, and build gates"]
  validate --> current{"Approval still current?"}
  current -->|No| bundle
  current -->|Yes| deliver{"Documentation only?"}
  deliver -->|Yes| main["Push validated docs directly to main"]
  deliver -->|No or mixed| pr["Use checked and approved pull request"]

Documentation Style Guide

Fullscreen diagram view.

Documentation Style Guide

Section titled “Documentation Style Guide”

Use this guide when writing the Simple version of a NutsNews Wiki article or reviewing it against the Technical version.

“Simple” still means complete

Section titled ““Simple” still means complete”

The Simple and Technical articles must agree about:

  • what the system does
  • who may perform an action
  • exact commands, values, URLs, and limits
  • warnings and stop conditions
  • how to check success
  • what to do when it fails
  • how to roll back safely

Use shorter sentences and explain technical words. Do not remove a fact or safety step just because it is complicated.

The files that belong together

Section titled “The files that belong together”

One original Technical source has:

  • audiences/simple/<source>.md
  • audiences/technical/<source>.md
  • diagrams/<source-without-md>.mmd

Update all four tracked files together. Generated site files, reports, caches, and inventory files are not hand-edited sources.

Where a document belongs

Section titled “Where a document belongs”
  • Current guides usually stay at the repository root.
  • updates/ appears in History as Updates.
  • reports/ appears as Reports.
  • archive/ appears as Archives.
  • ios/ appears as Classified notes.

History is not shown in search unless the reader enables Include History.

New-document example

Section titled “New-document example”

Create a valid blocked scaffold:

Terminal window
npm run docs:new -- CACHE_INVALIDATION_GUIDE.md --collection platform-and-data --section core-platform
npm run docs:prepare -- CACHE_INVALIDATION_GUIDE.md --force

The source uses a numeric unused order and metadata like this:

title: "Cache Invalidation Guide (Technical)"
description: "How NutsNews invalidates cached reader content safely."
wiki:
  source_route: "/technical/cache-invalidation-guide"
  simple_route: "/simple/cache-invalidation-guide"
  slug: "cache-invalidation-guide"
  primary_diagram:
    file: "diagrams/CACHE_INVALIDATION_GUIDE.mmd"
    accTitle: "Cache invalidation flow"
    accDescr: "An operator verifies scope, purges the selected cache, checks the reader response, and rolls back or escalates when verification fails."
  status: draft
  collection: platform-and-data
  section: core-platform
  order: 228
  approval:
    state: unreviewed
    publishing: blocked
    reviewed_by: pending
    reviewed_on: pending
    technical_source_hash: pending

Replace every TODO. Check the Technical source, Simple article, Technical mirror, diagram, commands, warnings, links, verification, and rollback.

After a human reviews the current bundle:

Terminal window
npm run docs:approve -- CACHE_INVALIDATION_GUIDE.md --reviewed-by "<human-reviewer>" --confirm-human-review

Then run:

Terminal window
npm run wiki:prepare
npm run validate:content
npm run validate:links
npm run validate:mermaid
npm run test:content-routes
npm run build

When an old approval becomes stale

Section titled “When an old approval becomes stale”

Changing the original Technical source makes its old approval invalid.

  1. Update both audience copies and the diagram.
  2. Keep every command, warning, success check, failure step, and rollback.
  3. Ask a human to review the current files.
  4. Run docs:approve again.
  5. Rerun all checks. Never edit only the hash or skip a failing gate.
Section titled “Diagrams, screenshots, and links”
  • Every article needs one useful Mermaid diagram with a clear accTitle and accDescr.
  • Use screenshots only when they make a control or visual state easier to find.
  • Every image needs useful alt text, a caption, and a local file. Remove secrets and personal data from images.
  • Link to original Markdown files with clear link text and exact heading fragments.
  • Add useful current guides to README.md, and link History records back to the current guide.

Before publishing

Section titled “Before publishing”
  • Simple and Technical facts match.
  • No command, warning, check, or rollback is missing.
  • Metadata and History placement are valid.
  • Diagram text and any screenshot text are accessible.
  • Human approval is current.
  • Every required command passes.

Documentation-only work may go directly to main after validation. Any site-code or mixed change follows the pull-request policy in AGENTS.md.

Section titled “Related docs”