How to handle images as part of the documentation?

[pmeier]

Currently we are storing images as part of the git repository. For example

• https://github.com/Quansight/ragna/blob/main/docs/assets/brand/logo-lockup-horizontal/logo-lockup-horizontal.png
• https://github.com/Quansight/ragna/blob/main/docs/how-tos/images/ragna-config-wizard.png

The former is an example where this fine, since the logo (or the brand in general), will change very rarely if ever.

The latter however is not a good use. A screenshot of components is quickly outdated (see #182) and needs replacing. Since an image is binary file, there is no diff that git could track. Meaning, whenever we update an image, we are completely replacing the old one. Ultimately this quickly leads to really large git repositories that I want to avoid.

I haven't done a proper survey on this. These are the options that I'm currently aware of:

1. Just ignore the issue. For active maintainers this is not really an issue, because when you have an initial checkout of the repository locally, all other changes are incremental. "Only" new contributors and our CI will be hit by this.
2. Use git-lfs to store the images. I've started that in document default login credentials #168, but faced some (internal) opposition. The main argument against it was that napari migrated away from it after facing some issues.
3. Go the napari way and create a separate documentation repository that holds the whole documentation except for the API documentation, which stays in the main repository as part of the docstrings.

My current order of preference 3. -> 2. -> 1. Opinions welcome.

[pavithraes]

Thank you for writing this up. :)

Re option 3, I'm a hesitant to do this because it adds friction for updating docs alongside the rest of the codebase. We'll need the development team to be very diligent, else the docs can quickly get out-of-date (we're seeing this in Nebari right now, and considering moving the docs repo back into the core-codebase repo).

Re option 2, the issues with git-lfs are related to storage/bandwidth costs. I see how this can be a problem for a comparatively large docs project like napari. But, I think at Ragna's documentation & team scale, we should be fine even with the free tier quotas? Maybe we can be more mindful about the image file sizes and use .webp format for compressed images, to allow us to use git-lfs. We can always move to a separate repo later if/when git-lfs stops working for us.

My preference is 2 -> 1 -> 3 -- I'm choosing 1 over 3 because if only new contributors and CI are mainly affected by option 1, they'll also be affected by option 3: contributors having extra steps to updating docs, and there will still be CI workflows on the docs repo, right (even if it needs to run comparatively fewer times)?

[dharhas]

My vote is 1 - ignore. This feels like premature optimization/ This will not be a image heavy repo and the small number of screenshots/images should not impact things significantly especially if we make sure to use properly sized, compressed images in an appropriate format.

for 2. git-lfs is an extra layer of complexity and every time I've been in a project that has used it things have gotten complicated.

for 3. I agree with @pavithraes , this introduces friction in keeping docs up to date.

[pmeier]

This feels like premature optimization

Well, this is one of the rare cases were worrying about this form the beginning actually pays off. If we commit images to the repository, their are there forever. No matter what we do in the future, this is not going to change.

This will not be a image heavy repo

How do we intend to document the UI? If we document it by screenshots, these images will have to be replaced regularly to keep them in sync with the code. And we would need a few to show

1. the new chat modal
2. the main page with the chat widget
3. the open side bar with the chat info, and
4. the open side bar with the source info.

Maybe we merge 3. / 4. with 2., but I don't think we can really go below that. And we can't make the screenshots to small in size, since for just 3 / 4 screenshots, we have quite a few details to highlight.