govoplan-docs/docs/DOCUMENTATION_LAYER_CONCEPT.md

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.

The editorial experience is defined in docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md: workflow guidance, structure reference, and shared design-pattern explanations are separate reading modes over this configured-system model.

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
• module manifest runtime documentation providers
• 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.

Module-Owned Documentation

Documentation is distributed over the modules that own the behavior. A module can register durable topics directly in its ModuleManifest.documentation tuple. Use this for stable explanations such as the module purpose, common workflows, policy hierarchy, route meaning, and links to public docs or repository docs.

When the text depends on active configuration, a module registers a provider in ModuleManifest.documentation_providers. The provider receives a DocumentationContext with the active registry, principal, settings, and a database session when available. The module can then describe the effective state without the docs module importing feature internals.

For example, govoplan-mail contributes static documentation for reusable mail profiles and a runtime tenant policy topic. If the effective tenant mail policy limits sending to approved profile ids and disables user, group, and campaign-local profiles, the runtime docs state that users can choose approved profiles but cannot bring arbitrary SMTP or IMAP servers at lower scopes. If the policy allows lower scopes, the same topic explains which scopes may define profiles and whether credential inheritance is locked.

Runtime providers must avoid leaking secrets. They should summarize posture, counts, source provenance, and enabling conditions rather than exposing credentials, hostnames, profile ids, or raw policy payloads unless the route is explicitly intended for that level of detail.

Conditions And Unlocks

Documentation topics can declare conditions:

• required modules
• one-of module alternatives
• modules that must be absent
• required capabilities
• required scopes or one-of scope alternatives
• configuration keys that influence the topic

The docs API classifies satisfied topics into their requested layer. Unsatisfied topics remain visible as available or evidence documentation when safe, with a reason such as a missing module, capability, or scope.

Topics can also declare related modules and unlock notes. This lets a module state that additional behavior becomes available when another module is installed. Runtime docs should link to the configured local behavior first and then to public module documentation for broader examples.

Admin And User Documentation

GovOPlaN has two documentation presentations over the same source model.

Admin documentation is allowed to be technical. It can expose installed module ids, route contributions, API paths, permissions, capability names, server configuration keys, policy source chains, migration notes, and operator evidence. This is the right place to explain exactly why a setting is available, which API applies it, and which configuration key or policy source controls it.

User documentation should be written for people without technical background. It should explain what the user can do, what they cannot do, and who to ask when a needed option is missing. It should avoid route names, API calls, raw policy payloads, internal module ids, and server configuration unless that information is genuinely meaningful to the user.

Each DocumentationTopic declares documentation_types, currently admin, user, or both. Runtime providers receive the requested type in DocumentationContext.documentation_type, so they can generate different text from the same effective configuration. For example, mail admin docs can mention mail profile policy sources and API endpoints, while user docs can simply say whether the user may choose an approved mail profile or add a local mail server.

The first presentation rule is:

• admin docs show technical context and evidence tables
• user docs show plain-language topics, examples, limits, and escalation paths
• both presentations are filtered by installed modules, active configuration, permissions, and safe disclosure rules

Localization

Localization should be prepared before substantial documentation text is added. Every durable topic should have a stable i18n_key. The English source text can remain in the manifest or provider, but topics may include locale-specific translations for title, summary, and body.

The docs API accepts a requested locale and falls back in this order:

• exact locale, such as de-AT
• base language, such as de
• English translation if present
• source text

This keeps the first implementation simple while avoiding a later rewrite of every module documentation contribution. A later dedicated translation catalog can still use the same i18n_key values.

Public Documentation For Missing Modules

The configured-system docs should not explain every uninstalled module in full. General documentation for the product and modules not installed in the current system belongs on https://govplan.add-ideas.de/, served by govoplan-web.

Runtime documentation should link to the public page when:

• an optional module is not installed
• a feature is unlocked by adding another module
• an example uses modules that are not active locally
• a user needs conceptual background beyond the configured system

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

Source Ownership

Documentation ownership follows behavior ownership:

• runtime documentation topics belong to the module that owns the route, policy, workflow, capability, or data model being explained
• repository docs belong to the repository that owns the implementation or durable architecture decision
• synced Gitea wiki pages are a publication surface for durable context, not a separate source of truth
• active Gitea issues are the source of truth for current work state, acceptance criteria, blockers, and triage decisions

The docs module renders and classifies documentation. It should not become the owner of feature-module explanations, and it should not copy backlog state into runtime documentation as if it were stable product behavior. When runtime docs link to an issue, they must present it as changing work state. When runtime docs link to repository docs or wiki pages, they may present the linked material as durable context if the owning repository treats it that way.

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.

Privacy And Permission Boundaries

Documentation is still a governed interface. Role-aware documentation must never use help text as a side channel for data, configuration, or capability details that the actor could not otherwise see.

User-facing topics may explain that a feature is unavailable and identify the kind of blocker, such as missing permission, disabled module, locked policy, or administrator configuration. They should not expose internal module ids, raw scope names, policy payloads, hostnames, tenant identifiers, profile ids, or other operational details unless the actor is already allowed to inspect that information.

Admin-facing topics may expose technical provenance, route ids, API paths, capabilities, configuration keys, policy source chains, and migration notes when the actor has the relevant administrative permission. Even then, runtime providers must summarize secrets and sensitive values as posture, counts, or source provenance. Credentials, tokens, private keys, raw payloads, and person-specific data stay out of documentation responses unless a dedicated audited administration route explicitly provides them.

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
• a provider contract for configuration-derived runtime topics

The first UI can be simple:

• configured modules
• visible routes
• active policies
• available-but-disabled evidence
• source links to wiki or repository docs
• module documentation topics with links and unlock notes

Once the source model is stable, feature modules can add richer documentation contributions through their manifests and capabilities.