search

fsspec / kerchunk

Cloud-friendly access to archival data
https://fsspec.github.io/kerchunk/
MIT License
284 stars 78 forks source link

Refreshing the documentation ? #410

Open NikosAlexandris opened 5 months ago

NikosAlexandris commented 5 months ago

The current Kerchunk documentation is minimal in a good way and the content to the point. Would you, however, see value added to refresh its look, feel and interactivity? Both https://squidfunk.github.io/mkdocs-material/ and https://jupyterbook.org/en/stable/intro.html are awesome tools to improve the user interface and experience of a project's documentation. @martindurant, any interest ?

martindurant commented 5 months ago

You are absolutely right, we could use a lot more and better quality documentation - the stuff we never get to while trying to chase features. The problem is more of getting the content out rather than the tools to make it into pages I think, but I'd be happy to consider any tool that helps. We do have some more book-like content as a pythia cookbook: https://projectpythia.org/kerchunk-cookbook/README.html

NikosAlexandris commented 5 months ago

You are absolutely right, we could use a lot more and better quality documentation - the stuff we never get to while trying to chase features. The problem is more of getting the content out rather than the tools to make it into pages I think, but I'd be happy to consider any tool that helps. We do have some more book-like content as a pythia cookbook: https://projectpythia.org/kerchunk-cookbook/README.html

This is based on Jupyter Book ? I have quite some experience using it.

Also, I guess it is known, yet another mention doesn't hurt! Good way(s) on doing documentation from https://diataxis.fr/:

The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

The principles laid out there have helped me a lot as I am working out a somewhat complex project at work.