The site's sidebar held the landing page and one guide next to seventeen architecture records, the migration register, the review procedure and five PRDs. Nothing there is secret -- every development page may be read by anyone -- but a reader who wants to know what Archie is and how to point an event at it was meeting contributor material with no signal that it was not for them. One source tree now yields two sets: public (index, guides/) under /docs/, and development (architecture/, prds/) under /dev/, each with its own artifact and its own derived sidebar. archive/, inspiration/, news/ and the credential notes stay out of both, unchanged. Selective PRD publication is gone rather than carried over. It existed only because settled architecture cites PRDs and a link to a held-back target fails the generator, so five PRDs published to keep those citations alive; with both halves of every such citation in the development set, the exception has no work left to do. Both sets are generated in one pass over one url map, so a citation that crosses between them resolves to the base its target is served under, and the refusal now fires only for a target genuinely in neither set. Widening the set exposed a scanner bug worth its own note: the link regex matched `Resolve[T](i, src, exportPath)` inside a code span and refused the page for a link to `i,`. Code spans and fenced blocks are now skipped, because what a renderer draws as a link is the only thing this tool may rewrite or refuse a page for. docs/prds/public-and-dev-docs.md records the decision. Draft: the three choices in it are the maintainer's, the write-up is not yet reviewed.
3.5 KiB
Public and development documentation -- design
Status: Draft Date: 2026-09-22
Problem
One published set carries both kinds of document. A reader who wants to know what Archie is and how to point an event at it lands in a sidebar that also holds the repository organisation rules, the migration decision register, the package review procedure and five PRDs. The PRDs are there for a reason that has nothing to do with the reader: settled architecture cites them, and the generator refuses a link whose target it holds back, so publishing them was the only way to keep those citations alive.
Mixing them is not an exposure problem. Every one of these documents can be public. It is a navigation problem: a customer reading the site meets contributor material with no signal that it is not for them.
Decision
One source tree, two published sets, two artifacts, two URL bases.
| Set | Holds | Served under | Artifact |
|---|---|---|---|
| Public | index.md, guides/ |
/docs/ |
docs/data/generated/docs.json |
| Development | architecture/, prds/ |
/dev/ |
docs/data/generated/dev-docs.json |
archive/, inspiration/, news/ and github-token.md stay out of both, for
the reasons the generator already records.
The two artifacts have the same shape. A renderer reads a second file and serves it under a second base; it needs no new field and no set discriminator, because the file a page arrived in is the set it belongs to.
Consequences the design depends on
Every PRD publishes. Selective PRD publication existed to keep citations
from settled architecture working. With both cited and citing documents in the
development set, that pressure is gone, and the rule that produced it goes with
it: prds/ is a development tree, not a list of exceptions.
Cross-set links resolve. A link from a public page to an architecture page rewrites to the development set's absolute path, and the reverse works the same way. Both sets are generated in one pass over one url map, so a link and its target cannot disagree about where the target lives. The generator's refusal still fires, now only for a target genuinely in neither set.
Assets keep the public base. docs/public/ is one file set, referenced
from either set, and serving one file under two paths would invent a second
location for it.
The sidebar stays derived from the directory layout, per set. A page added under a directory appears without a second edit, which is the property the current generator has and the reason its tree mirrors the tree on disk.
The public set is thin, and that is the honest state
Two pages: the landing page and the playbook guide. Nothing is lost by the
split, because a reader was never served by the seventeen architecture pages
next to them. The pages a public site needs (installation, configuration
reference, the event sources, the actions a playbook can run) are written into
guides/ and a reference/ tree as they are written, and each lands in the
public set with no generator change.
Verification
task docs:artifactwrites both files;task docs:artifact:checkfails on a stale copy of either, without touching the tree.- A link from the public set to a development page, and a link the other way, each resolve to the other set's base path in the generated body.
- A link to a page in neither set fails the generator, naming the file, the line and the target.
docsgenaccounts for both artifacts, so neither tool reports the other's file as unowned.