insforge--insforge/docs/asset-guidelines.md

Documentation Asset Guidelines

To keep the InsForge repository fast to clone, easy to maintain, and efficient for contributors, all documentation media assets should be reviewed and optimized before being committed.

Asset Size Expectations

• Prefer optimized assets whenever possible.
• Files larger than 5 MB should be reviewed carefully before being committed.
• Large media files increase repository clone size, slow documentation loading, and create unnecessary Git history churn.
• Consider whether an asset can be compressed or hosted externally before committing it to the repository.

Video Assets

• Use MP4 for documentation videos whenever possible.
• Compress screen recordings before committing them.
• Verify that text, cursor movements, and UI interactions remain clearly visible after compression.
• Avoid committing duplicate versions of the same video.

Compress MP4 Videos

Example command used for documentation video compression:

ffmpeg -i input.mp4 \
-vcodec libx264 \
-crf 28 \
-preset slow \
-an \
output.mp4

Image Assets

PNG Images

Compress PNG files before committing:

pngquant --force --ext .png image.png

JPEG Images

Optimize JPEG files before committing:

jpegoptim image.jpg

SVG Files

• Ensure SVG files contain vector data whenever possible.
• Avoid embedding large raster images as base64 content inside SVG files.
• Remove unnecessary metadata and optimize SVG exports before committing.

External Hosting

Consider external hosting when:

• Media files are exceptionally large.
• The asset is primarily demonstrative and does not need version control.
• The same content can be referenced through a stable URL.

Pull Request Checklist

Before submitting a pull request that includes documentation assets:

• Media files have been reviewed for size.
• Images have been optimized.
• Videos have been compressed where appropriate.
• Documentation references remain valid.
• No duplicate media assets have been committed.
• Large assets have a documented justification if optimization is not possible.

Recommended Tools

• FFmpeg
• pngquant
• jpegoptim
• SVGO