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,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.
|
||||
Reference in new issue
Block a user