docs: reorganize site structure using Diátaxis framework

- 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
This commit is contained in:
jaime.meza committed 2026-06-18 14:50:15 -05:00
1 parent 2cfb6f5ef7
commit b9a194f7c5
44 files changed
+200 -63

No files matched your search

@@ -0,0 +1,115 @@
---
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)