[Feature] Documentation experience: workflows, reference, and patterns #15

Open
opened 2026-07-09 13:24:39 +02:00 by zemion · 5 comments
Owner

Problem

The docs module already starts from the configured system, but the presentation still needs a clearer information architecture. Users need task-oriented guidance and short field explanations. Admins need the same workflows plus structure/reference mapping to API fields, permissions, routes, policy sources, and configuration keys. Both audiences need reusable explanations for shared UI patterns such as field help markers, disabled-action blockers, advanced panels, wizards, and policy provenance.

Proposed Capability

Implement the documentation experience described in docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md:

  • Workflows: outcome-oriented "I want to..." topics with audience-aware steps.
  • Reference: screen and field structure topics, with API/configuration/permission mappings in admin view.
  • Patterns: reusable explanations for platform UI behavior.
  • Help Center: a documentation-focused interface served by the same configured-system docs module, with route-aware and field-aware entry points from the application.

Ownership

  • Owning repository: govoplan-docs
  • Related module repositories: govoplan-core, govoplan-access, later each feature module that contributes docs metadata
  • Extension point or integration boundary: module manifests, runtime documentation providers, route metadata, field/reference DTOs, core WebUI help components

Acceptance Criteria

  • Docs topics can be grouped as workflow, reference, pattern, or system documentation without breaking existing configured/available/evidence classification.
  • User and admin views render different detail levels from the same configured-system context.
  • The docs WebUI exposes Workflows, Reference, Patterns, and This system modes.
  • Inline field help, route help, and blocked-action explanations can link to stable docs topics.
  • At least one access-administration workflow, one field/reference mapping, and one design-pattern topic are seeded.
  • Admin reference can show UI label, route/module, API method/path, API field, permission/scope, configuration or policy key, and safety/provenance notes where available.
  • User reference hides API and internal identifiers unless explicitly meaningful to the user.
  • Tests cover topic grouping, audience filtering, link/anchor generation, and configured/available/evidence behavior.

Verification Target

  • cd /mnt/DATA/git/govoplan-core && ./.venv/bin/python -m unittest tests.test_module_system
  • cd /mnt/DATA/git/govoplan-core && ./scripts/check-focused.sh before closing if core contracts or cross-module WebUI behavior changed.
  • Manual check: open /docs, switch user/admin mode, confirm workflow/reference/pattern navigation and contextual links.

Implementation Notes

Use DocumentationTopic.metadata for the first topic-kind slice. Add typed DTOs only after the first seeded topics prove the shape. Keep feature-module content contributed through manifests/providers/DTOs; the docs module should render and classify it without importing feature-module internals.

<!-- codex-manual-fingerprint:docs-experience-concept-2026-07-09 --> ## Problem The docs module already starts from the configured system, but the presentation still needs a clearer information architecture. Users need task-oriented guidance and short field explanations. Admins need the same workflows plus structure/reference mapping to API fields, permissions, routes, policy sources, and configuration keys. Both audiences need reusable explanations for shared UI patterns such as field help markers, disabled-action blockers, advanced panels, wizards, and policy provenance. ## Proposed Capability Implement the documentation experience described in `docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md`: - Workflows: outcome-oriented "I want to..." topics with audience-aware steps. - Reference: screen and field structure topics, with API/configuration/permission mappings in admin view. - Patterns: reusable explanations for platform UI behavior. - Help Center: a documentation-focused interface served by the same configured-system docs module, with route-aware and field-aware entry points from the application. ## Ownership - Owning repository: `govoplan-docs` - Related module repositories: `govoplan-core`, `govoplan-access`, later each feature module that contributes docs metadata - Extension point or integration boundary: module manifests, runtime documentation providers, route metadata, field/reference DTOs, core WebUI help components ## Acceptance Criteria - [ ] Docs topics can be grouped as workflow, reference, pattern, or system documentation without breaking existing configured/available/evidence classification. - [ ] User and admin views render different detail levels from the same configured-system context. - [ ] The docs WebUI exposes Workflows, Reference, Patterns, and This system modes. - [ ] Inline field help, route help, and blocked-action explanations can link to stable docs topics. - [ ] At least one access-administration workflow, one field/reference mapping, and one design-pattern topic are seeded. - [ ] Admin reference can show UI label, route/module, API method/path, API field, permission/scope, configuration or policy key, and safety/provenance notes where available. - [ ] User reference hides API and internal identifiers unless explicitly meaningful to the user. - [ ] Tests cover topic grouping, audience filtering, link/anchor generation, and configured/available/evidence behavior. ## Verification Target - `cd /mnt/DATA/git/govoplan-core && ./.venv/bin/python -m unittest tests.test_module_system` - `cd /mnt/DATA/git/govoplan-core && ./scripts/check-focused.sh` before closing if core contracts or cross-module WebUI behavior changed. - Manual check: open `/docs`, switch user/admin mode, confirm workflow/reference/pattern navigation and contextual links. ## Implementation Notes Use `DocumentationTopic.metadata` for the first topic-kind slice. Add typed DTOs only after the first seeded topics prove the shape. Keep feature-module content contributed through manifests/providers/DTOs; the docs module should render and classify it without importing feature-module internals.
zemion added the
type
feature
status
ready
area/api
area/webui
area/docs
codex/ready
labels 2026-07-09 13:24:39 +02:00
Author
Owner

Codex State: progress

Summary

  • Documented the documentation experience concept for workflow, reference, and pattern docs.
  • Created and synced the page-limited wiki entry for Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT.

Changed Files

  • docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md
  • README.md
  • docs/DOCUMENTATION_LAYER_CONCEPT.md

Verification

  • git diff --check

Next / Blocked

  • Implement topic-kind grouping and the Help Center navigation modes.

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Documented the documentation experience concept for workflow, reference, and pattern docs. - Created and synced the page-limited wiki entry for Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT. ### Changed Files - `docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md` - `README.md` - `docs/DOCUMENTATION_LAYER_CONCEPT.md` ### Verification - `git diff --check` ### Next / Blocked - Implement topic-kind grouping and the Help Center navigation modes. Suggested status label: `status/in-progress`
Author
Owner

Codex State: progress

Summary

  • Implemented topic-kind grouping in the docs context API while preserving configured/available/evidence layers.
  • Added access-owned workflow and field/reference topics plus a docs-owned field-help design pattern topic.
  • Reworked the docs WebUI into Help Center modes: Workflows, Reference, Patterns, and This system.

Changed Files

  • src/govoplan_docs/backend/api/v1/routes.py
  • src/govoplan_docs/backend/manifest.py
  • webui/src/api/docs.ts
  • webui/src/features/docs/DocsPage.tsx
  • webui/src/i18n/generatedTranslations.ts
  • tests/test_docs_context.py
  • /mnt/DATA/git/govoplan-access/src/govoplan_access/backend/manifest.py
  • /mnt/DATA/git/govoplan-core/tests/test_api_smoke.py

Verification

  • PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context
  • cd /mnt/DATA/git/govoplan-core && ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available
  • cd /mnt/DATA/git/govoplan-core/webui && npm run build
  • cd /mnt/DATA/git/govoplan-core && ./scripts/check-focused.sh

Next / Blocked

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Implemented topic-kind grouping in the docs context API while preserving configured/available/evidence layers. - Added access-owned workflow and field/reference topics plus a docs-owned field-help design pattern topic. - Reworked the docs WebUI into Help Center modes: Workflows, Reference, Patterns, and This system. ### Changed Files - `src/govoplan_docs/backend/api/v1/routes.py` - `src/govoplan_docs/backend/manifest.py` - `webui/src/api/docs.ts` - `webui/src/features/docs/DocsPage.tsx` - `webui/src/i18n/generatedTranslations.ts` - `tests/test_docs_context.py` - `/mnt/DATA/git/govoplan-access/src/govoplan_access/backend/manifest.py` - `/mnt/DATA/git/govoplan-core/tests/test_api_smoke.py` ### Verification - `PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context` - `cd /mnt/DATA/git/govoplan-core && ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available` - `cd /mnt/DATA/git/govoplan-core/webui && npm run build` - `cd /mnt/DATA/git/govoplan-core && ./scripts/check-focused.sh` ### Next / Blocked - Try the running dev UI at http://127.0.0.1:5174/docs?mode=workflows Suggested status label: `status/in-progress`
Author
Owner

Codex State: progress

Summary

  • Reworked the docs Help Center from mode switches to an audience toggle plus collapsible navigation tree.
  • Each tree node now opens a page with a right-side page outline; related topics link to the corresponding page.
  • Moved the help center surface onto the existing off-white panel tone.

Changed Files

  • webui/src/features/docs/DocsPage.tsx
  • webui/src/i18n/generatedTranslations.ts
  • ../govoplan-core/webui/src/styles/layout.css

Verification

  • govoplan-docs: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context
  • govoplan-core: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available
  • govoplan-core/webui: npm run build

Next / Blocked

  • Review current seeded topics and add missing workflow/reference/pattern content per module.

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Reworked the docs Help Center from mode switches to an audience toggle plus collapsible navigation tree. - Each tree node now opens a page with a right-side page outline; related topics link to the corresponding page. - Moved the help center surface onto the existing off-white panel tone. ### Changed Files - `webui/src/features/docs/DocsPage.tsx` - `webui/src/i18n/generatedTranslations.ts` - `../govoplan-core/webui/src/styles/layout.css` ### Verification - `govoplan-docs: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context` - `govoplan-core: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available` - `govoplan-core/webui: npm run build` ### Next / Blocked - Review current seeded topics and add missing workflow/reference/pattern content per module. Suggested status label: `status/in-progress`
Author
Owner

Codex State: progress

Summary

  • Adjusted the Help Center tree so navigation no longer exposes workflow/reference/pattern as top-level categories.
  • Tree nodes are now all clickable pages; the chevron alone expands and collapses children.
  • The tree renderer supports nested topic nodes through topic parent metadata.

Changed Files

  • webui/src/features/docs/DocsPage.tsx
  • webui/src/i18n/generatedTranslations.ts
  • ../govoplan-core/webui/src/styles/layout.css

Verification

  • govoplan-docs: git diff --check -- webui/src/features/docs/DocsPage.tsx webui/src/i18n/generatedTranslations.ts
  • govoplan-core: git diff --check -- webui/src/styles/layout.css
  • govoplan-docs: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context
  • govoplan-core: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available
  • govoplan-core/webui: npm run build

Next / Blocked

  • Review the resulting module/topic tree in the running UI and decide which content branches should be renamed or seeded first.

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Adjusted the Help Center tree so navigation no longer exposes workflow/reference/pattern as top-level categories. - Tree nodes are now all clickable pages; the chevron alone expands and collapses children. - The tree renderer supports nested topic nodes through topic parent metadata. ### Changed Files - `webui/src/features/docs/DocsPage.tsx` - `webui/src/i18n/generatedTranslations.ts` - `../govoplan-core/webui/src/styles/layout.css` ### Verification - `govoplan-docs: git diff --check -- webui/src/features/docs/DocsPage.tsx webui/src/i18n/generatedTranslations.ts` - `govoplan-core: git diff --check -- webui/src/styles/layout.css` - `govoplan-docs: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context` - `govoplan-core: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available` - `govoplan-core/webui: npm run build` ### Next / Blocked - Review the resulting module/topic tree in the running UI and decide which content branches should be renamed or seeded first. Suggested status label: `status/in-progress`
Author
Owner

Codex State: progress

Summary

  • Added a human-facing documentation taxonomy to the Help Center tree: About GovOPlaN, Working with GovOPlaN, Advanced, Modules, admin-only Administration, and conditional Troubleshooting and support.
  • Working with GovOPlaN is a nested branch with Basics and Common tasks, so workflow/pattern remain internal rendering metadata instead of navigation categories.
  • Modules remains a top-level overview with per-module subtrees; topic parent metadata still supports deeper nesting.

Changed Files

  • webui/src/features/docs/DocsPage.tsx
  • webui/src/i18n/generatedTranslations.ts

Verification

  • govoplan-docs: git diff --check -- webui/src/features/docs/DocsPage.tsx webui/src/i18n/generatedTranslations.ts
  • govoplan-docs: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context
  • govoplan-core: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available
  • govoplan-core/webui: npm run build

Next / Blocked

  • Review category names in the running UI, then seed missing content under each branch.

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Added a human-facing documentation taxonomy to the Help Center tree: About GovOPlaN, Working with GovOPlaN, Advanced, Modules, admin-only Administration, and conditional Troubleshooting and support. - Working with GovOPlaN is a nested branch with Basics and Common tasks, so workflow/pattern remain internal rendering metadata instead of navigation categories. - Modules remains a top-level overview with per-module subtrees; topic parent metadata still supports deeper nesting. ### Changed Files - `webui/src/features/docs/DocsPage.tsx` - `webui/src/i18n/generatedTranslations.ts` ### Verification - `govoplan-docs: git diff --check -- webui/src/features/docs/DocsPage.tsx webui/src/i18n/generatedTranslations.ts` - `govoplan-docs: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest tests.test_docs_context` - `govoplan-core: PYTHONPATH=/mnt/DATA/git/govoplan-core/src:/mnt/DATA/git/govoplan-access/src:/mnt/DATA/git/govoplan-docs/src:/mnt/DATA/git/govoplan-tenancy/src ./.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_docs_context_and_ops_status_are_available` - `govoplan-core/webui: npm run build` ### Next / Blocked - Review category names in the running UI, then seed missing content under each branch. Suggested status label: `status/in-progress`
zemion added the
module/docs
label 2026-07-10 19:50:59 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: add-ideas/govoplan-docs#15
No description provided.