- Group hub-documentation into explanation/, how-to/, and reference/ per Diátaxis - Move ifs-integration.md to new hoist-hub/ category - Add contributing/ category with Diátaxis framework explainer - Move tutorial-basics and tutorial-extras under docusaurus-guide/ - Rewrite docs/intro.mdx as site entry point with category navigation - Update all doc titles to reflect their Diátaxis type - Add HOIST logo to homepage hero and fix Get Started link
116 lines
4.0 KiB
Markdown
116 lines
4.0 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
title: How to Document a UI Flow
|
|
---
|
|
|
|
# UI Flow Development
|
|
|
|
## Quick Overview
|
|
|
|
A UI Flow can be either:
|
|
|
|
- A **standalone flow**, where each module contains a single screen, or
|
|
- A **composite flow**, which is more common and consists of multiple screens per module.
|
|
|
|
Regardless of the flow type, the standard design pattern is to provide both a **List View** and a **Detail View** within the same flow.
|
|
|
|
To optimize application object usage, the List and Detail views should be implemented on the same screen, even for complex flows. The behavior should be controlled through an input parameter named `mode`, which clearly defines the screen state (e.g., `list` vs. `detail`).
|
|
|
|
## Documentation Standard
|
|
|
|
Each screen and its associated blocks must be documented within a single specification/documentation file.
|
|
|
|
The documentation must include:
|
|
|
|
- A detailed explanation of the business flow
|
|
- Clear descriptions of expected user interactions, including mandatory fields, links to other screens, and button functionality
|
|
- Any assumptions or constraints related to usage
|
|
|
|
---
|
|
|
|
## List View Documentation Requirements
|
|
|
|
### Filters
|
|
|
|
- A detailed explanation of all available filters within the screen
|
|
- The purpose and behavior of each filter
|
|
- Whether the filter fires automatically or requires additional user interaction
|
|
|
|
### Actions and Navigation
|
|
|
|
A description of all supported actions and navigation paths, including:
|
|
|
|
- **Global actions** — affecting the entire screen
|
|
- **Row-level actions** — specific to individual records
|
|
|
|
### Permissions
|
|
|
|
- A clear definition of the permissions applicable within the screen context as defined by the HUB standard Profile Permissions
|
|
- Explanation of how permissions affect visibility, actions, or navigation
|
|
|
|
### External System Mapping
|
|
|
|
If the screen is integrated with an external system, a separate mapping table must be included. The mapping should clearly define field relationships and data flow between systems.
|
|
|
|
---
|
|
|
|
## Detail View Documentation Requirements
|
|
|
|
The Detail View documentation must clearly describe how users interact with a single record and how the screen behaves across different modes (e.g., view, edit, create).
|
|
|
|
### Data Representation
|
|
|
|
- A clear explanation of all fields displayed in the Detail View
|
|
- Identification of:
|
|
- Mandatory vs. optional fields
|
|
- Read-only vs. editable fields
|
|
- Derived or calculated values
|
|
- Default values and formatting rules (dates, numbers, statuses, etc.)
|
|
|
|
### Modes and State Management
|
|
|
|
- Documentation must describe all supported screen modes (e.g., View, Edit, Create)
|
|
- The behavior of the screen based on the `mode` input parameter must be explicitly defined
|
|
- Transitions between modes (e.g., entering edit mode, canceling edits, saving changes) should be clearly documented
|
|
|
|
### Actions and User Interactions
|
|
|
|
A detailed list of all actions available within the Detail View, such as:
|
|
|
|
- Save, Edit, Cancel, Delete
|
|
- Custom business actions
|
|
|
|
Expected behavior for each action, including:
|
|
|
|
- Validation rules
|
|
- Confirmation dialogs
|
|
- Success and error feedback
|
|
|
|
### Validation and Error Handling
|
|
|
|
- A comprehensive description of all validation rules applied to fields or sections
|
|
- Clear explanation of how validation errors are presented to the user
|
|
- Handling of backend or integration errors, including retry or recovery behavior
|
|
|
|
### Permissions and Access Control
|
|
|
|
Explicit definition of permissions affecting:
|
|
|
|
- Screen visibility and/or accessibility
|
|
- Field visibility
|
|
- Field editability
|
|
- Available actions
|
|
- Clarification on how permission changes impact the screen state and behavior
|
|
|
|
### Navigation and Context
|
|
|
|
- Description of how users reach the Detail View (e.g., from List View row selection)
|
|
- Definition of back-navigation behavior and context preservation
|
|
- Handling of unsaved changes when navigating away from the screen
|
|
|
|
### External System Mapping (If Applicable)
|
|
|
|
- Field-level mapping between the Detail View and external systems
|
|
- Identification of source-of-truth fields
|
|
- Synchronization behavior and timing (real-time vs. deferred)
|