232 lines
4.7 KiB
Markdown
232 lines
4.7 KiB
Markdown
|
# 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
|