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:
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)
|
||||
Reference in new issue
Block a user