Skip to content
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

Open
consideRatio opened this issue Nov 28, 2023 · 5 comments
Open

Reference documentation for each Panel #94

consideRatio opened this issue Nov 28, 2023 · 5 comments
Labels
documentation Improvements or additions to documentation

Comments

@consideRatio
Copy link
Member

consideRatio commented Nov 28, 2023

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.

@consideRatio consideRatio added the documentation Improvements or additions to documentation label Nov 28, 2023
@manics
Copy link
Member

manics commented Nov 28, 2023

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
Copy link
Member Author

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
Copy link
Member

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
Copy link
Collaborator

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.

@sgibson91
Copy link
Member

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

@sgibson91 sgibson91 removed their assignment Jan 10, 2024
@damianavila damianavila moved this to Todo 👍 in Sprint Board Jan 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

4 participants