# Documentation Layer Concept ## Purpose GovOPlaN Docs provides a documentation layer that starts with the configured system instead of the full theoretical product. Users should first see the modules, routes, permissions, policies, workflows, and operational choices that are actually available in their installation. Only after that should the documentation provide evidence about what else might be possible: installed-but-disabled features, optional modules, extension points, product capabilities, or examples from other configurations. ## Problem Traditional product documentation describes the full system. That creates avoidable complexity in configurable public-sector platforms because most users only need a slice of the system: - their tenant - their organization - their role - installed modules - enabled route contributions - enabled policy and configuration packages - visible capabilities When documentation begins with everything, the user must filter out unavailable features themselves. The docs module should invert that flow. ## Documentation Layers The module should classify documentation into three layers. ### Configured Configured documentation describes what is active for the current system and actor. It should be the default view. Inputs may include: - installed module manifests - enabled routes and navigation contributions - current tenant and organization context - effective permissions and roles - configuration packages - policy sources - capability registry entries - release catalog and module dependency metadata ### Available Available documentation describes behavior that exists in the installation but is not currently visible or enabled for the actor. Examples: - a module is installed but hidden by tenant configuration - a route exists but the actor lacks permission - a policy can be enabled by an administrator - a capability provider exists but no local binding is configured This layer should explain the enabling condition without exposing sensitive data. ### Evidence Evidence documentation describes possibilities beyond the configured surface. Examples: - optional modules not installed here - product documentation and examples - capability contracts that a module could provide - migration or rollout notes - links to wiki pages and durable repository docs Evidence should be discoverable, but it should not be the primary reading path for users trying to operate the current system. ## Source Model The docs module should consume documentation sources through explicit contracts: - module manifest documentation metadata - route metadata and page-level help references - capability metadata - configuration-package descriptions - release catalog entries - repository docs mirrored into Gitea wiki pages - manually curated admin documentation pages Feature modules should contribute documentation metadata without the docs module importing their internals. ## Rendering Model The runtime docs UI should be context-aware: - tenant-aware - organization-aware where relevant - role-aware - route-aware - module-aware - configuration-aware The same documentation source may render differently for an operator, module administrator, tenant administrator, or end user. The UI should make the current context explicit enough to avoid confusion, but it should avoid turning every page into a full configuration report. A compact "why am I seeing this?" explanation is usually enough. ## Governance Durable context belongs in repository docs and synced wiki pages. Active work belongs in Gitea issues. Runtime documentation should link both where helpful, but it should distinguish stable explanation from changing backlog state. Documentation sources should be auditable when they affect compliance, operator procedure, or policy explanation. Configuration-derived documentation should identify the source configuration package or policy source where possible. ## First Implementation Shape The first implementation should define: - the `docs` module manifest - documentation source DTOs - a source registry capability - a configured/available/evidence classifier - a minimal API for current-context documentation - a WebUI route contribution for the documentation browser The first UI can be simple: - configured modules - visible routes - active policies - available-but-disabled evidence - source links to wiki or repository docs Once the source model is stable, feature modules can add richer documentation contributions through their manifests and capabilities.