Create a plan for user facing documentation about the 'build your own image' feature

[yuvipanda]

As we roll out the 'build your own image' feature, we want more documentation on how people can do so. This task is to:

1. Decide what kind of documentation we are going to write
2. Where it will live
3. Create issues to track writing that documentation

Definition of Done

• We have a series of issues tracking the documentation to be written
• Champion is assigned for making sure these docs get written

Links

NASA-IMPACT/veda-docs#186 is NASA VEDA's attempt at helping write some of these docs

Follow-up issue

2i2c-org/docs#251

[maxrjones]

I've started using this intensively for https://github.com/maxrjones/zarr-obstore-performance and it's been wonderful - thank you @yuvipanda!

I think it'll be important to have separate documentation for users and developers. For example, in my current project I'm testing new commits to https://github.com/maxrjones/zarr-python/tree/object-store-perf and it's not super ergonomic to bump the commit in the DockerFile, shut down the server, and trigger a new build. I wonder if there's a better way to specify all the dev dependencies in the DockerFile and editable install the repo on the Hub.

[jnywong]

Hey @maxrjones ! Thanks for the feedback. I'm thinking about docs for 2i2c hubs in general, and I agree with your sentiment that authors of DockerFiles/image environments could benefit from a more streamlined workflow for local testing, using something like https://github.com/yuvipanda/test-jupyterhub-image-locally, before committing to a build with the GitHub CI/CD.

Do you think your community would benefit from a how-to guide for this?

[jnywong]

Suggested plan

• Add a basic, user-facing overview that covers the UX from the JupyterHub perspective (as opposed to the BinderHub UX) with some background on caching, etc.
• Add a small FAQ section that can be updated over time
• Curate a resource list that references upstream docs, e.g. repo2docker
• Add a developer-facing how-to guide on how to test images locally
  • Limit this to the scope of https://github.com/yuvipanda/test-jupyterhub-image-locally -- a comprehensive guide to image-building is not within the scope

[jnywong]

How does the above plan sound?

If there are no objections, I can break this out into smaller sub-issues for implementation.

[jnywong]

Here is an issue that captures the above plan for implementation that we can use to prioritise and enter this into our iteration planning for capacity and championing 👍

Marking this one as closed, but do feel free to chime in and re-open it if needed.