Sync wiki from project files
300
Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT.md
Normal file
300
Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT.md
Normal file
@@ -0,0 +1,300 @@
|
||||
<!-- codex-wiki-sync:320c1518180535134dcd6e2d -->
|
||||
|
||||
> 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.
|
||||
Reference in New Issue
Block a user