Documentation Sources
=====================

The Zero Board Computer project has two documentation surfaces, and
they hold different material on purpose.  This page is the canonical
statement of which surface holds what, who edits it, and how changes
flow.

Reference (this site)
---------------------

The Sphinx site you are reading.  Holds **normative** material -- the
content that implementations and conforming users must trust to be
correct.

- **What it holds:** the protocol specification, the API reference for
  the C and C++ libraries, operational guides (building, testing,
  security), worked examples, and proposals for future extensions.
- **Who edits it:** project maintainers, via pull requests against
  this repository.
- **Where it renders:** https://johnwbyrd.github.io/zbc/ (a move to
  ``docs.zeroboardcomputer.com`` is planned).
- **How changes flow:** edit ``docs/source/*.rst``, push to ``main``,
  the ``docs.yml`` workflow rebuilds the site and redeploys
  automatically.

Wiki (zeroboardcomputer.com)
----------------------------

The MediaWiki site at https://www.zeroboardcomputer.com.  Holds
**descriptive** material -- the content that captures what users
observe, accomplish, and learn from each other.

- **What it holds:** tutorials, how-to guides, troubleshooting
  collections, CPU and toolchain compatibility tables, ecosystem links
  (related projects, ports, forks), war stories, and the MediaWiki
  templates and navigation that the wiki itself uses.
- **Who edits it:** anyone with a wiki account.
- **Where it renders:** https://www.zeroboardcomputer.com.
- **How changes flow:** log in, click *Edit*, save.  No git, no review
  queue, no pull request.

When in doubt
-------------

Use this rubric to decide where a piece of content belongs:

- Does the content claim to be **normative** -- correct, authoritative,
  binding on conforming implementations?  → Reference.
- Does it describe what a user **observed**, accomplished, or learned
  the hard way?  → Wiki.
- Could it be **wrong** without breaking a conforming implementation?
  → Wiki.
- Is it a **tutorial**, a walkthrough, or a "how I got X working"
  story?  → Wiki.

A simpler version: if it has to be right for the protocol to work, put
it in the Reference.  Otherwise, the Wiki.

Regenerating wiki content
-------------------------

The wiki is authored directly at https://www.zeroboardcomputer.com.

There is no draft area in this repository.  There is no
``web/pages/`` mirror that gets synced.  When the wiki needs new
content -- tutorials, how-tos, compatibility tables, ecosystem entries
-- it gets written on the wiki, edited on the wiki, and lives on the
wiki.  The two doc surfaces hold *different* material; the wiki is not
regenerated from the spec, and the spec is not extracted from the
wiki.

The ``web/`` directory in this repository contains historical content
from an earlier model in which the wiki was treated as derived
documentation regenerated from the spec.  That model is superseded by
this page.  Retiring the legacy content under ``web/`` is tracked
separately; in the meantime, treat anything under ``web/`` as legacy,
not as the current source of truth for wiki content.  **The current
source of truth for wiki content is the wiki.**