DevDocs

dd_id_8f1b217e50

5. Documentation (Meta)

Goal

Goal: publish documentation through WordPress at https://docs.ai.drawconclusions.org from the sources in docs/devdocs/ (via a prepared bulk payload file). Domains are sourced from server/var_www/config.xml (source of truth).

Structure (Multidimensional)

Structure

WordPress should expose multiple entry points and pages, organized by these dimensions:

Devices: local, do-droplet, git-server
Docker containers
Installed software (git, docker, etc.)
App components (fe, be, database)
Individual documentation files (one page per file)

Cross-Linking (Duplication Is Expected)

Crosslinking

Each dimension page must include the information relevant to it, even if that duplicates content found elsewhere. Example: a page about "deployment" should also mention Git, and the Git page should also mention deployment. At minimum, include a link between related pages.

Output

DevDocs are WordPress pages served at https://docs.ai.drawconclusions.org. WordPress data (config, themes, plugins) is stored in server/var_www/devdocs_wp/ (server path: /var/www/devdocs_wp). DevDocs content is authored in docs/devdocs/ and transformed into a prepared payload file at server/var_www/devdocs_wp/wp_bulk_payload.json (server path: /var/www/devdocs_wp/wp_bulk_payload.json). Publish via python3 scripts_local/publish_devdocs.py.

Permalinks (Page IDs)

Permalinks

WordPress permalinks must use page IDs (e.g., /?page_id=123).
This prevents URL changes when pages move in the hierarchy.
Internal doc links should use page-id permalinks.

DevDocs vs rulebook

Rulebook

docs/rulebook/ is the primary authority for rules/contracts.
docs/devdocs/ is the source of truth for documentation content.
The prepared WordPress payload is stored at /var/www/devdocs_wp/wp_bulk_payload.json and is imported by the WordPress plugin.
server/var_www/devdocs_wp/ stores the WordPress data (config, themes, plugins) that powers DevDocs.
Changes must be made in docs/devdocs/, then published via python3 scripts_local/publish_devdocs.py.

Docs Freshness

Flag

The previous Docusaurus-based build and freshness flag are removed.
WordPress sync uses a hash manifest to update changed pages only (publish via python3 scripts_local/publish_devdocs.py).

Doc Layers

Layers

Pages (except Home) should be tagged with the doc_layer taxonomy.
Layer terms use the DEVELOPERDOCS_ID slug of the layer root page (for example, the top section pages set LAYER: <their DEVELOPERDOCS_ID> and all children inherit that layer).

Breadcrumbs show the page path up to Home.
Right sidebar includes Categories and Children sections.

UX Helpers

Ux

Back-to-top button appears when scrolling down (plugin: Codex Back To Top).
Collapsible Table of Contents appears when a page has multiple headings.
Top menu includes a default WordPress search bar at the far right (after the theme toggle).

Workflows

Workflow docs live in workflows.md and link to feature + test pages.

Transition Plan

Plan

The detailed migration plan lives in transition_plan_devdocs.md.

fixme

Islands

Islands group features into navigational sections (see islands.md).

Three-Layer Rule (Concept → Architecture → Implementation)

Layer

Every subject must be documented in three layers:

1) Concept (non-technical, user-facing meaning) 2) Architecture (technical overview, system-level design) 3) Implementation Notes (deep practical build details)

Each Concept page must link to its Architecture page.
Each Architecture page must link to its Implementation Notes page.
Each Implementation Notes page must link back to Architecture and list relevant tables/services/routes/files.
This is a general rule for DevDocs and should be applied going forward.
For rulebook: use this structure only when it best fits Codex understanding (apply selectively).

Security

WordPress uses the Codex WP security plugin to reduce self-disclosure and disable XML-RPC.

Draconai Documentation