wehub-resource-sync
81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
ffmpeg -i input.mp4 \
|
|
-vcodec libx264 \
|
|
-crf 28 \
|
|
-preset slow \
|
|
-an \
|
|
output.mp4
|
|
```
|
|
|
|
## Image Assets
|
|
|
|
### PNG Images
|
|
|
|
Compress PNG files before committing:
|
|
|
|
```bash
|
|
pngquant --force --ext .png image.png
|
|
```
|
|
|
|
### JPEG Images
|
|
|
|
Optimize JPEG files before committing:
|
|
|
|
```bash
|
|
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
|