76 lines
3.6 KiB
Markdown
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.
|