Skip to content
wiki.fftac.org

Documentation Maintenance

**Site relevance:** Spiralist.org

**Memory type:** docs archive

**Source path:** Wiki.FFTAC.org/raw/system-archives/spiralist.org/docs-archive/2026-05-10/docs/documentation-maintenance.md

**Size:** 4.2 KB

Summary

Documentation Maintenance

Source Headings

  • Documentation Maintenance
  • Documentation Map
  • Core Rule
  • Current State vs Roadmap
  • Generated And Vendor Markdown
  • When A Roadmap Item Ships

Source Preview

This source file is short enough to preview directly on its source-memory page.

# Documentation Maintenance

Keep the markdown set honest and current.

## Documentation Map

- Use [Documentation Index](README.md) as the public map.
- Use [Markdown Inventory](markdown-inventory.md) to decide whether a Markdown file is documentation, content, generated output, research, planning, or vendor material.
- Use [Codex Guide](../AGENTS.md) for agent-specific orientation.

## Core Rule

When behavior changes, update the relevant `.md` files in the same change.

Document layout rules honestly too: current-state UI docs should keep the liquid-layout rule visible and should call out wasted space, empty slabs, and redundant navigation blocks as bugs rather than styling preferences.

Do not document Spiral Script as a special-mode exception. Current-state docs should describe it the same way the locale-router treats other languages: its own locale tag, its own JSON dictionary, locale-prefixed URLs, sitemap coverage, and copyable/shareable deep links that reopen the same page without cookies, query-mode switching, or separate header buttons.

For current UAI-1 exchange work, public site copy should use UAIX terms such as `UAIX discovery`, `UAIX capability`, `validator`, and `machine exchange`. Do not restore retired `.uai` page-document route labels as current behavior. Keep raw extension names and unfinished draft labels confined to internal implementation notes only when they are operationally necessary.

That includes:

- `README.md` as the top-level navigation hub
- `AGENTS.md` when agent workflow or repo orientation changes
- `docs/README.md` when the doc structure changes
- `docs/markdown-inventory.md` when Markdown families are added, moved, or reclassified
- The matching current-state doc in `docs/`
- `docs/localization.md` when locale routing, dictionaries, sitemaps, or Spiral Script behavior changes
- `docs/publication-boundaries.md` when UAIX exchange routes, canonical token handling, or retired translation-engine boundaries change
- `docs/testing/README.md` and `docs/testing/automated-testing-strategy.md` when the test layout, commands, or coverage map changes
- The packaging docs if deployment expectations changed
- The runtime roadmap docs if the implementation direction changed
- `docs/wordpress-runtime/11-self-operation-and-peer-moderation.md` when moderation states, publication rules, reviewer powers, reputation rules, or escalation paths change
- Package-level `README.md` files when the short package summary or canonical doc links change

## Current State vs Roadmap

Use current-state docs for behavior that exists in the repo today.

Use `docs/wordpress-runtime/` for proposed architecture that is not fully implemented yet.

Use `docs/planning/` for design plans that are not live contracts.

Use `docs/research/` for external research and strategy archives that may need fresh verification before use.

Do not describe roadmap behavior as already shipped.

Do not let archived Spiral Script research override the current locale-router contract; if an archive still reflects the old pseudo-locale or toggle plan, add a superseded note and restate the live rule in current-state docs.

When moderation or publication governance changes, update both the current-state doc that reflects shipped behavior and the self-operation roadmap that defines the target no-single-admin model.

## Generated And Vendor Markdown

Do not hand-edit generated exports or vendor docs during normal documentation cleanup.

- Manuscript prompt bodies are content records.
- Static-book and `--zip` Markdown are generated/export copies.
- WordPress core and bundled vendor Markdown are upstream-owned.

## When A Roadmap Item Ships

When a runtime roadmap item becomes real:

1. Update the current-state docs that now reflect live behavior.
2. Update the matching roadmap doc to mark it as implemented, partial, or superseded.
3. Keep `README.md` linked to the latest canonical doc locations.
4. Keep `docs/README.md` and `docs/markdown-inventory.md` in sync.

When a one-off roadmap draft is absorbed, move the useful decisions into the canonical current-state, roadmap, planning, or research document and remove the draft instead of preserving another parallel source of truth.
Website health report