1

Repo docs DOCUMENTATION EXPERIENCE CONCEPT

Albrecht Degering edited this page 2026-07-09 13:25:22 +02:00

Table of Contents

• Documentation Experience Concept
• Goals
• Editorial Pillars
• Workflow Guidance
• Structure Reference
• Design Patterns
• Audience Model
• User View
• Admin View
• Presentation Shape
• Navigation Model
• Source Contract Direction
• Authoring Rules
• Implementation Path

Mirrored from /mnt/DATA/git/govoplan-docs/docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md. Origin: repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.

---

Documentation Experience Concept

GovOPlaN Docs should support three ways of understanding the configured platform:

• outcome-oriented workflow guidance
• structure-oriented reference documentation
• shared design-pattern explanations

These are different reading modes over the same configured-system knowledge. They should link to each other, respect user and admin perspectives, and keep the current installation as the primary source of truth.

Goals

The docs experience should answer these questions first:

• What can I do in this system?
• Which steps do I take to finish this task?
• What does this screen or field mean?
• Why does the interface behave this way?
• For admins: which API, permission, policy, or configuration source backs this screen?

It should not start from a full product manual. The current tenant, installed modules, enabled routes, permissions, and configuration decide what is shown as the default path.

Tracking issue: add-ideas/govoplan-docs#15.

Editorial Pillars

Workflow Guidance

Workflow docs are written from the reader's intent:

• "I want to create an API key."
• "I want to add a user to a group."
• "I want to configure a reusable mail sender."
• "I want to understand why an option is disabled."

Each workflow topic should have:

• outcome
• audience, usually user or admin
• prerequisites and blockers
• steps using visible interface labels
• expected result
• verification or review step when relevant
• related structure topics
• related design patterns

User workflow topics avoid API paths, internal module ids, raw permission names, and server configuration unless the user must act on them. They should explain who can help when a feature is not available.

Admin workflow topics can include technical context: API endpoints, required permissions, policy sources, configuration keys, migration or audit effects, and operator escalation paths.

Structure Reference

Structure docs describe what is visible on a screen and how it maps to platform contracts.

For users, structure reference is a field glossary:

• screen section
• visible label
• short plain-language meaning
• allowed values or validation
• where the value appears later
• common mistakes or limits

For admins, structure reference adds technical columns:

• route and module
• API method and path
• request or response field
• configuration key or policy field
• permission or scope
• provenance or inheritance rule
• audit/event implication
• safety or approval requirement

Structure docs should be linked from workflow steps and from inline field help. They should also link back to the workflows where the field is commonly used.

Design Patterns

Pattern docs explain repeated platform behavior once, then link to examples. They are not implementation tutorials; they explain what a reader should expect when they see a familiar affordance.

Initial pattern topics should include:

• field help marker next to labels
• disabled action and blocker explanation
• advanced options panel
• guided wizard and review step
• policy provenance and effective value rows
• status badges and problem lists
• in-app help menu and route-specific help context
• evidence, available, and configured documentation layers

The field help marker is the immediate example. In the app, FieldLabel can render InlineHelp beside form labels, and helpForFieldLabel currently maps known labels to short help text. The docs layer should treat this as a pattern: brief local explanation beside the field, with a link to the fuller structure or workflow topic when more detail is needed.

Audience Model

The docs source model may be shared, but presentation must be audience-specific.

User View

User docs should be calm, task-focused, and plain-language:

• start from "I want to..."
• use current interface labels
• explain limits and unavailable options without exposing internals
• show who can change configuration or permissions
• link to short field explanations and general patterns

User docs should not require knowledge of APIs, scopes, module ids, deployment configuration, or policy source chains.

Admin View

Admin docs should still be workflow-centered, but they may be technical:

• start from tenant, module, access, policy, and operator tasks
• expose API endpoints, DTO fields, permissions, module ids, capabilities, and configuration keys
• show route and field mappings
• explain provenance, inheritance, audit, and approval behavior
• include evidence for installed-but-disabled and optional capabilities

Admin docs are the right place to map an interface field to the API field and explain operational consequences.

Presentation Shape

The docs module should remain part of the platform because it needs the current configuration, registry, permissions, modules, routes, and policy state. The presentation should still feel like a documentation interface, not like another business module.

The recommended shape is:

• keep the docs backend module and configured-system API
• expose a full-page Help Center route served by the same server
• use lighter documentation chrome instead of normal module-workspace density
• keep route-aware entry points from the app shell, help menu, field help, and admin screens
• allow direct links such as /docs?type=user&topic=... or /docs?type=admin&route=...
• label the content as documentation for "this system" rather than as a generic marketing or product manual

This preserves third-person reference behavior while keeping the runtime benefits of a docs module. The server can still filter and explain content based on the actual installation.

Navigation Model

The Help Center should have primary modes:

• Workflows
• Reference
• Patterns
• This system

This system is the configured/available/evidence view that already exists in the first docs module slice. It should remain useful for admins and diagnostics, but normal users should mostly enter through Workflows or contextual help.

Each topic should support stable anchors and related-topic links:

• workflow topics link to fields and patterns
• field/reference topics link to workflows and API details when the reader is an admin
• pattern topics link to examples and the components that implement them
• unavailable topics link to the blocker and the actor who can resolve it

Source Contract Direction

The current DocumentationTopic contract can carry the first version through metadata, documentation_types, conditions, links, related_modules, and unlocks. As the docs experience matures, typed source DTOs should be added for clarity.

Recommended topic kinds:

• workflow
• reference
• pattern
• system

Recommended workflow metadata:

• outcome
• steps
• prerequisites
• result
• verification
• related_field_ids
• related_pattern_ids

Recommended reference metadata:

• route
• screen
• section
• fields
• api
• permissions
• configuration_keys
• policy_sources

Recommended field metadata:

• field_id
• label
• user_description
• admin_description
• api_field
• api_path
• configuration_key
• permission_scope
• validation
• provenance
• audit_event

Recommended pattern metadata:

• pattern_id
• purpose
• when_used
• user_explanation
• admin_explanation
• component_refs
• related_topics

Feature modules should contribute this data through manifests, runtime providers, route metadata, generated docs, or typed DTOs. The docs module renders and links the material; it should not import feature-module internals.

Authoring Rules

Workflow topics:

• use visible UI labels
• keep each step actionable
• mention blockers where the user would encounter them
• link to field/reference topics instead of repeating field tables

Reference topics:

• keep user columns short
• put API, permission, and configuration mapping in the admin view
• identify generated or runtime-derived values
• avoid exposing secrets or raw policy payloads

Pattern topics:

• explain the pattern once
• link to current examples
• distinguish user meaning from admin/operator meaning
• stay stable even when individual screens change

Implementation Path

1. Keep the existing context API and add topic kind metadata.
2. Add docs-topic grouping for workflows, reference, patterns, and system diagnostics.
3. Add backend DTOs for field/reference metadata after the metadata shape is proven with one or two modules.
4. Rework the WebUI into a Help Center route with audience mode, search, contextual anchors, and the four navigation modes.
5. Connect in-app help entry points to docs topics: help menu, route context, inline field help, disabled-action blockers, and admin reference tables.
6. Seed access-module content first because users, groups, roles, sessions, and API keys have clear user/admin splits and concrete API mappings.
7. Add pattern topics for existing core UI behavior, starting with field help, blockers, advanced panels, wizards, and policy provenance.
8. Add tests for classification, audience filtering, topic linking, and route or field anchor generation.

The first shippable milestone should be small: one workflow, one structure reference, and one design-pattern topic for access administration, all filtered by the current docs context and visible in the Help Center.