282 lines
12 KiB
Markdown
282 lines
12 KiB
Markdown
# 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.
|