-
Notifications
You must be signed in to change notification settings - Fork 23
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reference documentation for each Panel #94
Comments
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? |
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. |
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 :) |
As part of #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. |
After the following PRs, I hope it'll be easier for folk to add to and improve the documentation for this project :) |
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:
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.
The text was updated successfully, but these errors were encountered: