Files
archie/docs/prds/public-and-dev-docs.md
T

76 lines
3.6 KiB
Markdown

# 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:artifact` writes both files; `task docs:artifact:check` fails 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.
- `docsgen` accounts for both artifacts, so neither tool reports the other's
file as unowned.