Croissant / Eclair docs

[joaquinvanschoren]

Hi all,

I was wondering how to make the Eclair docs easier to find, but at the same time how the Croissant documentation structure itself could be improved.

For Eclair, there are full (mkdock-based) docs: https://eclair-docs.github.io but this is nowhere referenced from any Croissant docs. The source is in mlcommons/croissant/eclair/docs, but rendered with github.io from another repo (which exists solely to hold the rendered docs).

The sitation is similar for other subprojects (e.g., python API, editor and health check), they have readmes in subfolders but these aren't referenced very well.

Croissant has different documentation pages:

• A page on the mlcommons website: https://mlcommons.org/working-groups/data/croissant/ - this is focussed on governance, with links to the github repo and the editor (a bit hard to find), and a clear callout link to the spec.
• The GitHub readme at https://github.com/mlcommons/croissant - a good intro but limited since there are no links to the other readmes
• Readme files for different subprojects, somewhat scattered in different subfolders.
• A github.io page which mirrors the readme, but referenced nowhere and it has broken links: https://docs.mlcommons.org/croissant/

What would be the best way forward for the Eclair docs and the Croissant docs in general?

Some options:

• Restructure the readme.md to better mention the subprojects (Eclair, editor, health) but also the Python API (e.g., install instructions are again in a subfolder that isn't referenced). The Eclair docs would still be hosted in another repo then, which is weird and it complicates rebuilding the docs.
• Create dedicated Croissant docs (e.g. using mkdocs). This is easy to do, it's just a .yml file that points to the different .md files scattered over the repo). Then we'd have dedicated documentation pages, with tabs for the spec, API, editor, health, Eclair,... We can then ask the MLCommons folks to host it on https://docs.mlcommons.org/croissant/ (instead of defaulting to the readme file).

Thoughts? I personally think the latter is better long-term: it will look better / more professional, and isn't much work. The MLCommons page could point more clearly to the consolidated Croissant docs, and vice versa, the new docs will point back to explain the governance.

Thanks!
Joaquin

[benjelloun]

Thanks for kicking off this discussion Joaquin! I'm also in favor of having dedicated documentation using mkdocs. We can use this transition as a good incentive to organize the Croissant documentation in a more sensible way, and identify areas that need improvement.

Do you have a suggestion on how to get this effort started? Would you like to lead a discussion on this topic at an upcoming Croissant meeting?

Best,
Omar

[joaquinvanschoren]

That sounds like a good idea. I can also try making a rough draft first :)