platform/doc/assets/README.md

Documentation Assets

Directory Structure

assets/
├── diagrams/    # Architecture and flow diagrams
├── images/      # Screenshots and general images
├── logos/       # Framework and package logos
└── icons/       # UI and feature icons

Asset Organization

1. Diagrams

• Architecture diagrams
• Flow charts
• Sequence diagrams
• Component diagrams
• Class diagrams

Example naming:

diagrams/
├── architecture/
│   ├── system_overview.svg
│   ├── package_dependencies.svg
│   └── service_interaction.svg
├── flows/
│   ├── request_lifecycle.svg
│   ├── event_handling.svg
│   └── queue_processing.svg
└── sequences/
    ├── authentication_flow.svg
    ├── job_dispatch.svg
    └── model_events.svg

2. Images

• Documentation screenshots
• Example outputs
• Visual guides
• Tutorial images

Example naming:

images/
├── getting_started/
│   ├── installation_step1.png
│   ├── configuration_step2.png
│   └── running_tests_step3.png
├── tutorials/
│   ├── creating_service_provider.png
│   ├── setting_up_queue.png
│   └── configuring_cache.png
└── examples/
    ├── api_response.png
    ├── console_output.png
    └── test_results.png

3. Logos

• Framework logos
• Package logos
• Integration logos
• Partner logos

Example naming:

logos/
├── framework/
│   ├── full_logo.svg
│   ├── icon_only.svg
│   └── text_only.svg
├── packages/
│   ├── container_logo.svg
│   ├── events_logo.svg
│   └── queue_logo.svg
└── partners/
    ├── vendor_logo.svg
    ├── cloud_logo.svg
    └── tools_logo.svg

4. Icons

• Feature icons
• UI elements
• Status indicators
• Action icons

Example naming:

icons/
├── features/
│   ├── caching.svg
│   ├── queuing.svg
│   └── routing.svg
├── status/
│   ├── success.svg
│   ├── warning.svg
│   └── error.svg
└── actions/
    ├── configure.svg
    ├── deploy.svg
    └── monitor.svg

Naming Conventions

1. File Names

   • Use lowercase
   • Use underscores for spaces
   • Include category prefix
   • Include size/variant suffix
   • Examples:
     • diagram_system_overview_large.svg
     • screenshot_installation_step1.png
     • logo_framework_dark.svg
     • icon_feature_cache_16px.svg

2. Directory Names

   • Use lowercase
   • Use descriptive categories
   • Group related assets
   • Examples:
     • diagrams/architecture/
     • images/tutorials/
     • logos/packages/
     • icons/features/

File Formats

1. Diagrams

   • SVG (preferred for diagrams)
   • PNG (when SVG not possible)
   • Source files in separate repo

2. Images

   • PNG (preferred for screenshots)
   • JPG (for photos)
   • WebP (for web optimization)

3. Logos

   • SVG (preferred for logos)
   • PNG (with multiple resolutions)
   • Include source files

4. Icons

   • SVG (preferred for icons)
   • PNG (with multiple sizes)
   • Include source files

Usage Guidelines

1. Diagrams

   • Use consistent styling
   • Include source files
   • Maintain aspect ratios
   • Use standard colors

2. Images

   • Optimize for web
   • Use descriptive names
   • Include alt text
   • Maintain quality

3. Logos

   • Follow brand guidelines
   • Include all variants
   • Maintain proportions
   • Use vector formats

4. Icons

   • Use consistent style
   • Include multiple sizes
   • Optimize for display
   • Follow naming pattern

Contributing Assets

1. Adding New Assets

   • Follow naming conventions
   • Use appropriate format
   • Include source files
   • Update documentation

2. Updating Assets

   • Maintain version history
   • Update all variants
   • Keep source files
   • Document changes

3. Removing Assets

   • Update documentation
   • Remove all variants
   • Archive if needed
   • Document removal

Best Practices

1. File Organization

   • Use correct directories
   • Follow naming patterns
   • Group related assets
   • Maintain structure

2. Version Control

   • Commit source files
   • Track large files properly
   • Document changes
   • Use git LFS if needed

3. Quality Control

   • Optimize for web
   • Check resolutions
   • Verify formats
   • Test displays

4. Documentation

   • Reference assets properly
   • Include alt text
   • Document sources
   • Credit creators

Questions?

For questions about assets:

1. Check naming conventions
2. Review directory structure
3. Consult usage guidelines
4. Ask in pull request