Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/wiki/foundations/Documentation-Convention.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,9 @@ folder this playbook publishes from. Of the seventeen public repositories in the
use `docs/wiki`; `architests`, `value-objects` and `purview-dev.github.io` publish from `docs`, and
`pm-skills` publishes no documentation folder at all, documenting itself through its skills. What the
rule requires is the part those repositories share: the documentation lives with the code it describes,
as Markdown, with its navigation in the folder beside it. The folder name is the only part that varies.
as Markdown, with its navigation in the folder beside it. The folder name is the part that varies. Some
repositories still carry a site configuration file from before the portal read Markdown directly; it is
harmless, the portal ignores it, and this playbook does not ship one.
[Cross-Repository Harvest](../governance/Cross-Repository-Harvest.md) records the deviations by name.

## Why
Expand Down
8 changes: 4 additions & 4 deletions docs/wiki/governance/Cross-Repository-Harvest.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,10 @@ publish from `docs`, and `pm-skills` publishes no documentation folder at all, d
through its eighteen skills.

That is not seventeen repositories getting a rule wrong; it is one repository's shape written down as if
it were universal. What the rule actually requires is that the documentation lives with the code — the
folder name is the part that varies, and nothing else does, because no repository carries a site
configuration any more (`astroc4` publishes `docs/wiki` and nothing beside it). The convention page now
says so, and names each deviation rather than pretending the rule was followed.
it were universal. What the rule actually requires is that the documentation lives with the code, as
Markdown the portal can read: the folder name is the part that varies, and `astroc4` publishes
`docs/wiki` with no site configuration beside it, which is the shape the rule now states. The convention
page now says so, and names each deviation rather than pretending the rule was followed.

## How it is enforced

Expand Down
Loading