Reference documentation for each Panel

[consideRatio]

I think we should look to establish a reference section (see diataxis.fr) in the docs at https://jupyterhub-grafana.readthedocs.io/, where we describe each panel in each dashboard.

I think we should focus on letting the reference describe individual panels, like how diataxis.fr suggests a reference guide is written:

The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way. Whereas the content of tutorials and how-to guides are led by needs of the user, reference material is led by the product it describes.

Why start with reference docs?

I propose we improve the docs of grafana-dashboards by starting at the reference docs, I've found it to be a good starting point in order to build more advanced docs that connects pieces as that is then offloaded from needin to do reference like descriptions.

[manics]

How much overlap is there between the reference doc for a panel, and the description attribute of the panel? Can they be treated as the same?

[consideRatio]

Very good point, I've not thought this through that much but I was thinking that maybe it could make sense to link to the rendered docs from the description that presents itself. If this is a good idea or not depends on things like what format we are constrained to in the description and if its suitable to rendered in the sphinx-docs as well etc.

[sgibson91]

I'm going to try and move this issue forward a little bit by opening a PR that creates the diataxis structure in the docs folder of the repo. Hopefully this will reduce the barrier a little way to folks filling those sections out since they won't need to worry about where they should put their contribution, only writing it :)

[yuvipanda]

As part of https://github.com/jupyterhub/grafana-dashboards/pull/90 I've tried to also add more detailed references in the description, and it would be lovely in the long term to autogenerate reference docs from that.

[sgibson91]

After the following PRs, I hope it'll be easier for folk to add to and improve the documentation for this project :)

• #96
• #97