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,8 @@
{
"label": "How-to Guides",
"position": 2,
"link": {
"type": "generated-index",
"description": "Step-by-step guidance on how to document each section of a HUB spec correctly."
}
}
@@ -0,0 +1,50 @@
---
sidebar_position: 3
title: How to Document Custom Fields
---
# Custom Fields Documentation Standard
Custom fields must be explicitly documented, especially when they are integrated with or sourced from external systems (e.g., IFS).
## Definition and Scope
Each custom field must be clearly identified as custom (i.e., non-core or non-standard). The documentation must specify:
- The external system it is connected to (if applicable)
- Whether the field is optional, conditional, or mandatory
Custom fields may not be applicable across the entire application and may vary by:
- Portal owner
- Tenant
- Deployment context
## Applicability and Visibility
Documentation must clearly state:
- Which portal owners or user groups can see or use the field
- Any conditions that control visibility or availability
If a custom field is only relevant in specific modules, flows, or screens, this must be explicitly stated.
## Behavior and Constraints
The business purpose of each custom field must be documented. Any constraints or special behavior should be described, including:
- Validation rules
- Read-only or system-managed values
- Dependency on external system data availability
## External System Dependency
For fields connected to external systems:
- Clearly define the source of truth
- Describe synchronization behavior (real-time vs. asynchronous)
- Document fallback or error behavior if the external system is unavailable
## Impact on UI and Integration
The presence or absence of custom fields must not negatively impact standard application behavior. Any UI or integration logic that depends on custom fields must be clearly documented to avoid assumptions in shared or multi-tenant environments.
@@ -0,0 +1,129 @@
---
sidebar_position: 2
title: How to Document Mockups & Screenshots
---
# Mockups & Screenshots Documentation Standard
Mockups and screenshots are mandatory artifacts used to visually communicate screen behavior, layout, and user interactions. They must complement — not replace — written documentation and be consistent with the defined UI Flow and business logic.
## Purpose and Scope
Mockups/screenshots must clearly illustrate:
- Screen layout and structure
- Key user interactions and navigation paths
- Differences between List and Detail views
- Variations across screen modes (e.g., View, Edit, Create)
Visual assets should reflect the intended final behavior, not exploratory or experimental designs unless explicitly stated.
---
## Mockup Requirements
### Level of Fidelity
**High-fidelity mockups** are preferred for:
- New screens
- Complex user interactions
- Approval-ready specifications
**Low- or mid-fidelity mockups** are acceptable for:
- Early discovery phases
- Internal alignment or conceptual discussions
:::note
Low/mid-fidelity mockups must be clearly labeled as **non-final**.
:::
### Consistency
Mockups must align with:
- Design system / UI guidelines
- Naming conventions used in documentation
- Field labels, actions, and terminology defined in the spec
Any intentional deviation from standards must be explicitly documented.
### Coverage
Mockups should cover, at minimum:
- List View (default state)
- Detail View (view-only mode)
- Detail View (edit/create mode)
- Empty states (no data)
- Error or validation states (if applicable)
---
## Screenshot Standards
### When to Use Screenshots
Screenshots may be used when:
- Documenting existing or legacy functionality
- Validating implemented behavior against specifications
- Providing references for enhancements or bug fixes
### Quality and Clarity
Screenshots must:
- Be clear, legible, and high resolution
- Exclude irrelevant UI elements or personal data
- Highlight the relevant area using annotations if needed
---
## Annotation and Labeling
All mockups and screenshots must include:
- Screen name and version
- Mode or state (e.g., List, Detail – Edit)
Annotations should be used to:
- Explain business rules
- Clarify hidden or dynamic behavior
- Call out permissions, validations, or conditional visibility
Annotations must be concise and consistent with written documentation terminology.
---
## Traceability and Referencing
Each mockup or screenshot must:
- Be referenced explicitly in the documentation (e.g., "See Mockup M-01")
- Map clearly to documented requirements, flows, or actions
If multiple screens share similar layouts or behavior, this should be stated to avoid redundancy.
---
## Versioning and Maintenance
Mockups and screenshots must be versioned and updated with:
- Functional changes
- UI changes impacting user behavior
Outdated visuals must not remain referenced in active documentation. Version history or change notes should be maintained when mockups are updated.
---
## Tools and Formats
| Format | Accepted |
|--------|----------|
| PNG | Yes |
| JPG | Yes |
| Figma (embedded link) | Yes |
Source design files should be accessible to relevant stakeholders when possible. Screenshots embedded in documentation must preserve original aspect ratios.
@@ -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)