- 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
3.2 KiB
sidebar_position, title
| sidebar_position | title |
|---|---|
| 2 | 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.