Skip to content

🖼️ Documentation Image Organization

A guide to working with images in the KDP documentation

Overview

KDP documentation uses a section-specific image organization pattern where each documentation section has its own imgs/ directory containing relevant images. This approach provides better organization and makes it clear which images are used in each section.

📁 Directory Structure

Each major documentation section has its own imgs/ directory:

docs/
├── features/
│   ├── imgs/             # Feature-specific images
│   │   └── models/       # Generated model diagrams
│   ├── overview.md
│   └── ...
├── advanced/
│   ├── imgs/             # Advanced feature images
│   └── ...
├── getting-started/
│   ├── imgs/             # Getting started images
│   └── ...
└── ...

🔄 Image Organization Script

The scripts/organize_docs_images.sh script handles image organization:

  1. It categorizes images into common, feature-specific, and advanced types
  2. It distributes these images to appropriate section folders
  3. It ensures generated model diagrams are correctly placed in the features/imgs/models/ directory

This script runs automatically during documentation generation:

make generate_doc_content

🎨 Image Categories

Images are organized into three main categories:

  1. Common Images (distributed to all sections):
  2. Model_Architecture.png - Main architecture diagram
  3. features_stats.png - Feature statistics visualization
  4. time_vs_nr_data.png - Performance comparison chart
  5. time_vs_nr_features.png - Feature scaling chart

  6. kdp_logo.png - Project logo

  7. Feature-Specific Images (in features/imgs/ and getting-started/imgs/):

  8. cat_feature_pipeline.png - Categorical feature processing pipeline
  9. numerical_example_model.png - Example numerical feature model

  10. And others related to core feature types

  11. Advanced Feature Images (in advanced/imgs/, optimization/imgs/, and examples/imgs/):

  12. TransformerBlockAllFeatures.png - Transformer block architecture
  13. numerical_example_model_with_distribution_aware.png - Distribution-aware encoding

  14. And others related to advanced features

  15. Model Diagrams (in features/imgs/models/):

  16. Automatically generated diagrams showing different model architectures
  17. Created by the generate_model_diagrams.py script

🖊️ Adding New Images

When adding new images to the documentation:

  1. Place the image in the appropriate section's imgs/ directory
  2. Reference it in the Markdown using a relative path: ![Description](imgs/image_name.png)
  3. Run make generate_doc_content to ensure proper organization

📋 Best Practices

  1. Use Descriptive Filenames:
  2. Choose clear, descriptive names: categorical_processing_flow.png not img1.png

  3. Use snake_case for filenames

  4. Optimize Images:

  5. Compress images to reduce file size
  6. Use PNG for diagrams and screenshots

  7. Keep dimensions reasonable (800-1200px width for most images)

  8. Include Alt Text:

  9. Always provide descriptive alt text: ![Distribution-aware encoding architecture](imgs/distribution_aware.png)

  10. Keep Images Relevant:

  11. Only include images that add value to the documentation
  12. Remove unused images using make clean_old_diagrams

🔍 Finding Unused Images

To identify potentially unused images:

make identify_unused_diagrams

This will generate an unused_diagrams_report.txt file listing images that may not be referenced in the documentation.