danth
doc: replace large image files with external URLs
Replace large image files in the repository with external URLs to reduce
repository size and encourage future large assets to be added
externally.
The images were uploaded to GitHub with its drag-and-drop functionality.
Although the images can no longer be viewed offline, this is a
worthwhile trade-off given the rarity of this use-case.
My main concern with keeping these "non-essential" documentation assets in the repository makes it very tempting to override them when updating them. In the future for example, this would cause the Git repo to be 100MB large with over 90% attributed to non-essential visualizations, where we essentially never care about anything other than the latest version of the visualizations, unlike the source code where history is valuable.
Working with such a bloated Git repo would be rather annoying. The fact that the .tar.gz is smaller is merely a side-effect.
For reference, I have thought about implementing something in the future where demonstrations could be automatically generated, which would keep the documentation in sync with the functionality and this could be used in PRs and issues to find color inconsistencies. In that case, somewhat frequent changes to these visualizations would merely bloat the repository size.
I have thought about implementing something in the future where demonstrations could be automatically generated
Same - just automatically screenshot the testbeds once the target is fully loaded. The NixOS testing framework already has the functionality for this.
In this case the screenshots could just be dependencies of the docs derivation, and built when required.
However it would only show the initial page, which in some cases is not as interesting as a page further into the interaction. For example, the initial page of VSCode is not as interesting as having a file open. Also, we would have to maintain code to detect when the target is fully loaded.
