Skip to content
ALNEAS Ecosystem

ALNEAS Documentation Governance Policy

ALNEAS Documentation Governance Policy

Section titled “ALNEAS Documentation Governance Policy”

Status: Active (2026-10-17)
Applies to: eaos-workspace (public/private), tools, web-framework, github-docs

[!NOTE] AI agents and automated scripts can consume the raw markdown directly at:
/policies/documentation-policy.md

github-docs serves as the centralized public portal for browsing, searching, and navigating the entire ALNEAS ecosystem. This policy formalizes our documentation standard to ensure exceptional readability for humans, unambiguous context for AI agents, and complete prevention of confidential information leaks.

1. Single Source of Truth (SSOT) and One-Way Sync

Section titled “1. Single Source of Truth (SSOT) and One-Way Sync”
Content Category Canonical SSOT Location Treatment in github-docs
Global Navigation, Showcase, Governance Policies github-docs Maintained and edited directly here
Technical Guides & Project Documentation Respective Owning Projects Ingested one-way from approved public manifests
Extracted API Reference (JSDoc / TypeDoc) Upstream Source Code Generated via docgen and merged with translation dictionaries
Private Enterprise Guides & Internal Plugins Private Repositories Strictly excluded (Provide standalone public summaries if needed)
Customer Configs, Receipts, Secret Runbooks Private Host Environments Strictly excluded
Drafts, Research Notes, Migration Scratchpads Upstream docs/ Excluded by default unless promoted to official guides
AI Action Skills (SKILL.md) Owning Repositories Kept distinct from human API references

Core Rules

Section titled “Core Rules”
  1. No Reverse Syncing: If an error is spotted in an ingested guide, fix it in the upstream repository, never in github-docs.
  2. Never Edit Generated Artifacts: Files under src/content/docs/**/api.md or generated/ are overwritten during builds.
  3. Audit Trails: Sync tools track upstream commit SHA, relative path, and SHA-256 content hashes to detect drift.

2. Diátaxis Framework

Section titled “2. Diátaxis Framework”

Every page must fulfill exactly one of the four Diátaxis archetypes:

               [Practical / Task-Oriented]
                         ▲
     Tutorials (Learning)│ How-To Guides (Problem-Solving)
─────────────────────────┼────────────────────────────────
     Explanation (Theory)│ Reference (Information-Oriented)
                         ▼
             [Theoretical / Understanding]
  1. Tutorial: A linear, step-by-step lesson taking a beginner from 0 to 1 without branching.
  2. How-To Guide: A recipe addressing a specific real-world problem with prerequisites.
  3. Reference: Machine-precise specifications, parameters, and card-style examples.
  4. Explanation: High-level architecture, design decisions, and ecosystem context.

3. Five-Section Project Landing Standard

Section titled “3. Five-Section Project Landing Standard”

Every project overview page must follow this structure:

  1. Hero & Mission: One-sentence value proposition and target audience.
  2. Core Tenets: 3 to 4 architectural differentiators (why this exists).
  3. Synergy Matrix: How this project integrates with other ALNEAS tools.
  4. Quick Tour: Under 30 lines of code showing a working example.
  5. Deep Dives & API Links: Pointers to Guides and Reference cards.

4. Open-Core Showcase vs Private Runbooks

Section titled “4. Open-Core Showcase vs Private Runbooks”
  • Public Showcase: Open-core features, commercial plugin specifications, and extension points are fully documented publicly to maximize discoverability and upgrade value.
  • Confidential Material: Production host credentials, IP addresses, database schemas, internal receipts, and un-obfuscated trade secrets are strictly restricted to internal portals (INTERNAL=true) protected by Cloudflare Access.