- 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
4.0 KiB
sidebar_position, title
| sidebar_position | title |
|---|---|
| 1 | 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
modeinput 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)