Merge pull request jupyterhub#97 from sgibson91/diataxis-docs

Setup diataxis framework in docs folder and reorganise

docs/contributing.md

@@ -1,3 +1,4 @@
+(contributing)=
 # Contributing
 
 ## Upgrading grafonnet version

docs/explanation/index.md

@@ -0,0 +1,20 @@
+(explanation)=
+# Explanation
+
+The documentation in this sections aims to _explain_ and _clarify_ a particular
+topic within the project in order to broaden the reader's understanding.
+
+```{note}
+[Read more about the Explanation quadrant of the diataxis framework.](https://diataxis.fr/explanation/)
+```
+
+```{attention}
+This documentation is a Work in Progress!
+Please see our [contributing guide](contributing) if you'd like to add to it.
+```
+
+% As files are added into this folder, you can add them to the below section so
+% that they appear in the table of contents
+```{toctree}
+:maxdepth: 2
+```

docs/howto/index.md

@@ -0,0 +1,19 @@
+(howto)=
+# How-To Guides
+
+The documentation in this section is _goal-oriented_ and designed to guide the
+reader through specific steps to reach that goal.
+
+```{note}
+[Read more about the How-To quadrant of the diataxis framework.](https://diataxis.fr/how-to-guides/)
+```
+
+```{attention}
+This documentation is a Work in Progress!
+Please see our [contributing guide](contributing) if you'd like to add to it.
+```
+
+```{toctree}
+images.md
+user-diagnostics.md
+```

docs/index.md

@@ -16,19 +16,49 @@ to help with this. It uses [jsonnet](https://jsonnet.org/) and
 [grafonnet](https://github.com/grafana/grafonnet-lib) to generate dashboards completely
 via code. This can then be deployed on any Grafana instance!
 
-## How-to
+## How the documentation is organised
+
+We are currently using the [diátaxis framework](https://diataxis.fr/) to organise
+our docs into four main categories:
+
+- [**Tutorials**](tutorials): Step-by-step guides to complete a specific task
+- [**How-To guides**](howto): Directions to solve scenarios faced while using the project. Their titles often complete the sentence "How do I...?"
+- [**Explanation**](explanation): More in-depth discussion of topics within the project to broaden understanding.
+- [**Reference**](ref): Technical descriptions of the components within the project, and how to use them
+
+### Tutorials
+
+```{toctree}
+:maxdepth: 2
+tutorials/index.md
+```
+
+### How-to Guides
 
 ```{toctree}
 :maxdepth: 2
-howto/deploy.md
-howto/user-diagnostics.md
-howto/images.md
+howto/index.md
+```
+
+### Explanation
+
+```{toctree}
+:maxdepth: 2
+explanation/index.md
+```
+
+### Reference
+
+```{toctree}
+reference/index.md
 ```
 
 ## Contributing
 
+Thank you for considering contributing! You can find some details to help you
+get started in the sections below.
+
 ```{toctree}
 :maxdepth: 2
 contributing.md
 ```
-

docs/reference/index.md

@@ -0,0 +1,20 @@
+(ref)=
+# Reference
+
+The documentation in this section provides technical descriptions of the
+components used throughout the project, and how to use them.
+
+```{note}
+[Read more about the Reference quadrant of the diataxis framework.](https://diataxis.fr/reference/)
+```
+
+```{attention}
+This documentation is a Work in Progress!
+Please see our [contributing guide](contributing) if you'd like to add to it.
+```
+
+% As files are added into this folder, you can add them to the below section so
+% that they appear in the table of contents
+```{toctree}
+:maxdepth: 2
+```

docs/howto/deploy.md → docs/tutorials/deploy.md

@@ -1,5 +1,6 @@
-# How to deploy the dashboards
-
+(tutorials:deploy)=
+# Deploying the dashboards
+
 ```{warning}
 ANY CHANGES YOU MAKE VIA THE GRAFANA UI WILL BE OVERWRITTEN NEXT TIME YOU RUN deploy.bash.
 TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN
@@ -20,16 +21,15 @@ TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN
    [node-exporter](https://github.com/prometheus/node_exporter) and
    [cadvisor](https://github.com/google/cadvisor) enabled. In
    addition, you should scrape metrics from the hub instance as well.
-
-
+
     ```{tip}
     If you're using a prometheus chart older than version `14.*`, then you can deploy the dashboards available prior to the upgrade, in the [`1.0 tag`](https://github.com/jupyterhub/grafana-dashboards/releases/tag/1.0).
     ```
-   
-3. `kube-state-metrics` must be configured to add some labels to metrics 
+
+3. `kube-state-metrics` must be configured to add some labels to metrics
    [since version 2.0](https://kubernetes.io/blog/2021/04/13/kube-state-metrics-v-2-0/).
    If deployed with the prometheus helm chart, the config should look like this:
-   
+
    ```yaml
    kube-state-metrics:
       metricLabelsAllowlist:
@@ -38,7 +38,7 @@ TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN
          # allowing all labels is probably fine for nodes, since they don't churn much, unlike pods
          - nodes=[*]
    ```
-   
+
    ```{tip}
    Make sure this is indented correctly where it should be!
    ```
@@ -50,7 +50,6 @@ TO MAKE CHANGES, EDIT THE JSONNET FILE AND DEPLOY AGAIN
    selecting 'API Keys'. The admin permission is needed to query list of data sources so we
    can auto-populate template variable options (such as list of hubs).
 
-
 ## Additional prometheus exporters
 
 Some very useful metrics (such as home directory free space) require
@@ -134,7 +133,6 @@ spec:
 
 You will likely only need to adjust the `claimName` above to use this example.
 
-
 (howto:deploy:per-user-home-dir)=
 ### Per-user home directory metrics (size, last modified, total entries, etc)
 
@@ -223,7 +221,6 @@ spec:
 
 You will likely only need to adjust the `claimName` above to use this example.
 
-
 ## Deploy the dashbaords
 
 There's a helper `deploy.py` script that can deploy the dashboards to any grafana installation.
@@ -250,4 +247,3 @@ If your Grafana instance uses a self-signed certificate, use the `--no-tls-verif
 ```bash
 ./deploy.py <your-grafana-url> --no-tls-verify
 ```
-

docs/tutorials/index.md

@@ -0,0 +1,19 @@
+(tutorials)=
+# Tutorials
+
+The documentation in this section are step-by-step guides that lead the reader
+through completing a specific task.
+
+```{note}
+[Read more about the Tutorials quadrant of the diataxis framework.](https://diataxis.fr/tutorials/)
+```
+
+```{attention}
+This documentation is a Work in Progress!
+Please see our [contributing guide](contributing) if you'd like to add to it.
+```
+
+```{toctree}
+:maxdepth: 2
+deploy.md
+```