google / google/neuroglancer

docs: create tooling for automated image/video creation and/or decide on storage method for large assets for docs

Open
#1,033 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1.5k
Forks
389
Avg merge
3d 21h
Merged PRs (30d)
3

Description

I think it's worth reading from https://github.com/google/neuroglancer/pull/1006#issuecomment-4565951563 onwards in relation this. As a very brief summary, we now have user facing documentation. And naturally people want to include videos and images in this documentation. However, that will quickly bloat the size of the git repository.

The two main ideas to solve these are:
1. Automated tooling to create images and videos. These would also be likely more helpful as a form of documentation, because users could hopefully use the same states. Including state with a static image is something that could be requested, but hard to enforce.
2. Storing the images and videos in a separate bucket or platform (e.g. youtube) or using git lfs. Storing in a separate bucket or git lfs introduces extra costs though. And either way, these images and videos risk going out of date and creating maintenance burden.

Overall option 1 would seem to be the best, and could be done incrementally. Both @chrisj and @jbms have very good suggestions in #1006 about how this incremental procedure could be performed.

Contributor guide

Open the contributing guide

Research direction

Read the discussion from the linked comment onward, including the suggestions in pull request #1006. Compare incremental automated image/video generation with a separate bucket or platform and git LFS, then document a decided approach, its maintenance implications, and how completion will be verified.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.