294 lines
9.2 KiB
Markdown
294 lines
9.2 KiB
Markdown
# 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.
|