diff --git a/Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT.md b/Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT.md new file mode 100644 index 0000000..01dc3ba --- /dev/null +++ b/Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT.md @@ -0,0 +1,300 @@ + + +> 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.