Documentation navigation and ownership

For HSLG, reserve https://media.hslg.uk/app/code/, /app/architecture/ and /app/user-guide/. Reserve /devlog/ for one complete chronological log page. Each Code module has a module page and file-level child pages; other HSLG plugins can use their own root namespace in future.

Each generated WordPress page has a stable documentation key and ownership post meta. Existing unowned pages, even with the same slug, are never replaced. The independently installable wordpress/hslg-docs-publisher plugin checks existing paths, ownership metadata and parent paths before editing. Activation and release-bundle changes automatically import eligible pages; no administrator WP-CLI publication command is necessary. Optional WP-CLI inspection remains for recovery and diagnostics. It does not delete pages when a document disappears from a release; removals need explicit review.

WordPress revisions are the on-site editing history. The development chronicle is the project-action history; these are not interchangeable. Canonical Markdown and publication JSON travel in the source archive, making WordPress recoverable after a migration. Edits made solely in the WordPress editor block automatic publication of conflicting pages; incorporate them into canonical source before retrying. Unlimited WordPress page revisions (WP_POST_REVISIONS=true) are required to preserve the full edit timeline.

Why WordPress pages are not the source of truth

The permanent documentation is versioned alongside source code in the HSLG archive. WordPress is the browsable publication of that information. Editing only a WordPress page creates knowledge that can be lost when a server fails and cannot be reproduced by another AI or build environment. Conversely, editing only Markdown without publishing it leaves the operator with stale instructions. Both states are failures that the release process must detect.

Information architecture

Under /app/code/, organize modules and their individual classes/files by source responsibility. Code pages answer how a specific part works and what changes when it is edited. Under /app/architecture/, explain why this technology/design was chosen, alternatives, costs, risks, ownership and deferred decisions. Under /app/user-guide/, explain workflows from the view of customers, venue staff or administrators. /app/licensing/ contains commercial evidence. /app/disaster-recovery/ is the single authoritative whole-stack recovery page. /devlog/ is one chronological operational record, not a marketing changelog.

Future plugins need separate namespaces so their documentation does not collide with this project's page hierarchy. Page identity relies on stable keys and HSLG ownership metadata, not only human titles. A renamed visible heading should not force deletion of the existing WordPress post or loss of revision history.

What makes a complete page

A Code page should identify its module purpose, important entry points, data/authorization boundaries, error handling, integrations and tests. It should distinguish current behaviour from planned behaviour and link to related architecture and user flows. An architecture page should explain context and evidence for the decision, measurable benefits, operational and financial costs, alternatives, risks and reconsideration triggers. A User Guide should give actual customer steps, expected outcomes, errors and support diagnostics. Low-level source indexes may be shorter, but must never be labelled as equivalent to a full system explanation.

A page may legitimately run several thousand words when it explains a complicated recovery or payment system. Length alone is not the goal: each paragraph must add a specific detail, decision or actionable instruction. Repeated boilerplate or copied source code without interpretation should be rejected. Screenshots and diagrams are welcome when they reveal a state transition, boundary or spatial relationship that prose cannot describe as efficiently; decorative images do not count as explanation.

Publishing, revisions and conflict handling

The publisher creates new pages once and updates existing IDs through WordPress post APIs. A changed page creates a normal WordPress revision; an unchanged page is left alone. A manually edited page or a colliding unowned slug blocks publication rather than being overwritten. The development chronology also records what source/release changed. WordPress revisions and source history are complementary: one tracks published page content, the other tracks why a release changed and how it was tested.

Maintaining accuracy

Every source change identifies its affected documentation pages, including Code references, architecture implications, user-visible changes and disaster-recovery impact. The release manifest records source paths and hashes so omissions are detectable. A human reviewer still needs to read affected complex pages because a file hash cannot explain why a new security check matters. Unknown decisions remain labelled unresolved. This avoids the false appearance of completeness produced by auto-generated directory lists.