Skip to content

Screenshot Guidelines

This document provides guidelines for creating and managing screenshots for the Enjade user documentation.

Overview

Screenshots are essential for helping users understand the Enjade interface and workflows. This documentation currently contains placeholder markers that indicate where screenshots should be added.

Screenshot Locations

All screenshots should be placed in the /docs/user/docs/assets/screenshots/ directory, organized by topic:

screenshots/
├── getting-started/     # Login and onboarding
├── viewer-panel/        # Viewer panel interface
├── datagrid/            # DataGrid application
├── admin/               # Admin panel
└── viewers/             # Viewer integrations

Required Screenshots

High Priority

Getting Started

  • login-page.png - Main login page
  • viewer-panel-login.png - Viewer panel login with project selector

Viewer Panel

  • panel-layout.png - Complete panel layout
  • connection-status.png - Connection status indicators
  • properties-grouped.png - Grouped properties view
  • properties-table.png - Three-column properties view
  • property-types.png - Different property type examples
  • element-selection.png - Element selected in viewer
  • type-assignments.png - Type assignment interface
  • batch-editing.png - Batch edit panel

DataGrid

  • grid-overview.png - Full grid interface
  • column-management.png - Column operations
  • filtering.png - Filter interface
  • batch-edit.png - Batch editing dialog
  • saved-views.png - View management panel
  • footer-aggregations.png - Footer with aggregations

Admin Panel

  • dashboard.png - Admin dashboard
  • navigation.png - Sidebar navigation
  • projects-list.png - Projects list
  • project-create.png - Project creation form
  • classification-tree.png - Classification hierarchy
  • cost-plan.png - Cost plan structure

Medium Priority

  • Version history views
  • Advanced filtering
  • Virtual folders
  • Viewer integrations
  • Batch operations

See /docs/user/docs/assets/screenshots/README.md for the complete list.

Screenshot Standards

Technical Requirements

Aspect Requirement
Resolution Minimum 1200px wide for main views
Format PNG for UI screenshots, JPG for photos
File Size Keep under 500KB per screenshot
DPI 72 DPI (standard screen resolution)

Composition Guidelines

  1. Browser Window
  2. Use a consistent browser and window size
  3. Remove browser UI when possible (full-screen app views)

  4. Ensure clean, uncluttered browser chrome

  5. Content

  6. Show realistic but non-sensitive data
  7. Use example project names like "Sample Project"

  8. Avoid personal information or real project data

  9. Interface State

  10. Show the interface in its default state
  11. Highlight relevant features being documented

  12. Keep consistent UI theme (light or dark mode)

  13. Annotations

  14. Add annotations sparingly
  15. Use consistent color and style for callouts
  16. Ensure text is readable at documentation size
  • macOS: Built-in Screenshot tool (Cmd+Shift+4/5)
  • Windows: Snipping Tool or Snip & Sketch
  • Linux: GNOME Screenshot or Spectacle
  • Cross-platform:
  • Greenshot (annotation support)
  • ShareX (Windows, advanced features)
  • Flameshot (Linux, annotation support)

Taking Screenshots

Preparation

  1. Set up test data
  2. Use "Sample Project" or "Demo Building" as project name
  3. Populate with representative but generic data

  4. Ensure sufficient variety to demonstrate features

  5. Configure interface

  6. Set consistent theme (recommend light mode for docs)
  7. Use standard browser zoom (100%)

  8. Clear any notifications or overlays

  9. Plan the shot

  10. Identify what feature to demonstrate
  11. Determine the minimal area needed
  12. Consider how it will appear in documentation

Capture Process

  1. Main Interface Screenshots 

    - Open the target interface/page
- Ensure it's in the desired state
- Capture at least 1200px wide
- Include relevant UI elements

  2. Dialog Screenshots 

    - Open the dialog/modal
- Show with realistic content filled in
- Include surrounding context if helpful
- Capture at minimum 600px wide

  3. Workflow Screenshots 

    - Capture multiple steps if needed
- Show before and after states
- Highlight changed elements

Post-Processing

Editing

  1. Crop - Remove unnecessary UI elements
  2. Resize - Scale to appropriate documentation size
  3. Optimize - Compress without losing quality
  4. Annotate - Add callouts if needed (use consistently)

Optimization Tools

  • ImageOptim (macOS) - Lossless compression
  • PNGGauntlet (Windows) - PNG optimization
  • OptiPNG (Cross-platform) - Command-line PNG optimizer
  • TinyPNG (Web) - Online compression

File Naming

Use descriptive, kebab-case names: 

✓ Good: viewer-panel-properties-grouped.png
✓ Good: datagrid-batch-edit-dialog.png
✗ Bad: Screenshot 2024-01-15.png
✗ Bad: IMG_0123.png

Adding Screenshots to Documentation

Replacing Placeholders

Current documentation uses this pattern:

!!! info "Screenshot Placeholder"
    **TODO: Add screenshot of login page**

    ![Login Page Placeholder](../assets/screenshots/getting-started/login-page.png)

    *The login page showing email and password input fields with the Enjade logo*

To replace:

  1. Create the screenshot following guidelines above
  2. Save with the exact filename shown in the placeholder
  3. Place in the correct directory
  4. Remove the "Screenshot Placeholder" admonition
  5. Keep the image reference and caption

Result:

![Login Page](../assets/screenshots/getting-started/login-page.png)

*The login page showing email and password input fields with the Enjade logo*

Adding New Screenshots

When adding screenshots not marked as placeholders:

![Descriptive Alt Text](../assets/screenshots/section/filename.png)

*Italic caption describing what the screenshot shows*

Quality Checklist

Before adding a screenshot, verify:

  • [ ] Shows relevant feature clearly
  • [ ] Uses appropriate resolution (1200px+ for main views)
  • [ ] Contains no sensitive information
  • [ ] File size is reasonable (<500KB)
  • [ ] Uses proper file format (PNG for UI)
  • [ ] Has descriptive filename
  • [ ] Saved in correct directory
  • [ ] Properly referenced in markdown
  • [ ] Has descriptive caption

Updating Screenshots

When the UI changes:

  1. Identify outdated screenshots
  2. Retake using same guidelines
  3. Maintain same filename
  4. Update caption if needed
  5. Commit with clear message: "docs: Update [feature] screenshot"

Accessibility

Ensure screenshots are accessible:

  1. Alt Text - Provide descriptive alt text for screen readers
  2. Captions - Add captions to provide context
  3. Contrast - Ensure sufficient contrast in annotations
  4. Text Size - Don't rely on small text in screenshots; describe in documentation

Examples

Good Screenshot Practices

Example 1: Feature Overview - Full interface view - Clear feature visibility - Realistic sample data - Appropriate resolution

Example 2: Detailed View - Zoomed to relevant area - Highlights specific control - Shows interaction state - Includes visual context

Common Issues to Avoid

❌ Too small - Can't read text or see details ❌ Too cluttered - Distracting elements visible ❌ Inconsistent - Different theme/style across docs ❌ Outdated - Shows old UI version ❌ Low quality - Blurry or pixelated

Contributing

To contribute screenshots:

  1. Fork the repository
  2. Create screenshots following these guidelines
  3. Place in appropriate directory
  4. Update documentation to reference screenshots
  5. Submit pull request with:
  6. Clear description of screenshots added
  7. Confirmation of guideline compliance
  8. Reference to issue if applicable

Questions?

For questions about screenshot guidelines or documentation updates, please:

  • Open an issue on GitHub
  • Contact the documentation team
  • Refer to the main contributing guide