Rework documentation structure according to diataxis.fr (formerly DIVIO)

[consideRatio]

Proposed change

I'd like for us to restructure our documentation to use the Diátaxis Framework described at https://diataxis.fr. The gist is to structure documentation content in four separate sections (Tutorials, How-to guides, Explanation, Reference). I think it would be phenomenal to get documentation structured like that as it would make it so much easier to write and navigate documentation if we have a structure like that.

I had written a motivation for following this structure, but @evildmp motivates it better in this one minute video segment.

Recommendations to learn about Diátaxis Framework

Update: this video covers it all well in ~20 minutes.

1. To skim through this youtube video.
2. To consider how writing text under these categories would work out.

Suggested process towards implementing a new structure for z2jh.jupyter.org docs

I'd love feedback from @jupyterhub/jupyterhubteam if you think that: a) this is reasonable change and acceptable to work towards, and b) if the chronologically ordered steps below represent a reasonable process to implement the change or if you have ideas on how we can go about making this change structured and acceptable to review along the way.

Scope of an initial PRs work

• [ ] Plan mapping of the old docs structure to new structure To map existing documentation to fit in a new structure and reach tentative agreement on the structure. At this point, no change the documentation itself should be made. The goal is to review the structure itself on a high level before proceeding.
• [ ] Plan adjustments that can't wait To outline all the documentation adjustments needed in various sections. Perhaps we will end up needing some additional sections to tie our structure together into something cohesive etc? This task is about outlining such needs rather than writing such documentation itself.
• [ ] Implement adjustments that can't wait

Continuation work

Going onwards, we can try to update our docs to be written to fit better in the section it is now within. These changes can be better scoped to smaller parts.

[minrk]

I think that's good in general. Roughly how would you say what we have now should be binned into these categories? To what degree would it necessitate a large rewrite vs mostly moving files around?

[consideRatio]

To what degree would it necessitate a large rewrite vs mostly moving files around?

I suggest we take initial steps by mostly to moving files and sections of files around. Following those initial steps have been merged, I suggest subsequent PRs update texts to better fit the style of the section they now belong to.

So I would say the bare minimum is mostly moving files around, and the proper rework can be seen as a stretch goal that we work towards over time in separate PRs.

Roughly how would you say what we have now should be binned into these categories?

I did some initial mapping work to see if it felt viable and it does, but I haven't gone through all sections and I haven't come up with a presentation of such mapping.

But as an example, having listened to the distinction of what a tutorial and what a how-to guide should be, I think perhaps the z2jh docs should have a Getting started tutorial where minikube is used to install a local Helm chart that anyone can reproduce reliably. Then, the learning goals are that users learn how to basic things in k8s, configure the Helm chart, etc. Following that, they may be ready to do how-to guides of setting up k8s on cloud provider X and follow other how-to guides on how to configure something or read via the reference docs etc.

This screenshot from the video motivates to me why we should let the initial getting started tutorial use minikube rather than point directly to cloud provider setups etc for example.

[minrk]

This screenshot from the video motivates to me why we should let the initial getting started tutorial use minikube rather than point directly to cloud provider setups etc for example.

Minikube has lots of rough edges and platform-sensitive issues. It is often inconsistent across users' environments, and not available to a lot of folks. It also lacks features of 'real' deployments like public IPs that are important to https setup, etc. I think if we want to eliminate choice in a tutorial, picking one cloud provider would result in a better tutorial than picking minikube.

[consideRatio]

@minrk ah yes good point, hmmm perhaps we could use something like Katacoda or something as well for an easier tutorial that bypasses the k8s setup as katacoda can get it done automatically for us I think.

Ping @manics regarding this who have done nice work already towards something like this.

[manics]

One thing to consider is whether having all four docs on the same readthedocs site is the best option? For instance if we use Katacoda or some other interactive platform for tutorials would we still want something on RTD, or would we keep all tutorial related content in one place.

Another thing worth doing is going through the existing docs and classifying them. For instance, if it turns out that most of our docs fit into one or two categories then instead of a big reorganisation to the docs and having to add redirects (or breaking external links... a pet hate of mine) we could make minor changes, and then work out where to put the additional types of docs.

Last question (for now 😃 ) is whether this is just for Z2JH, or JupyterHub as a whole? It definitely makes sense to start with one repo, but if we want to roll it out across multiple Jupyter projects we should think about how to make the docs consistent across all repos, and ideally how to avoid duplicating content.

[consideRatio]

One thing to consider is whether having all four docs on the same readthedocs site is the best option?

I'd be happy with a pattern like "oh now we have moved 75% of from here to , perhaps we move the last 25% as well?", but cautious towards "hmmm, if we move 25%, should we move 100% while we are at it?".

Another thing worth doing is going through the existing docs and classifying them.

I see the first part of work towards this restructure would be to go through and propose a new structure, which means to classify our docs to fit in the sections tutorials, how-to, explanation, reference - but to classify them using self figured out topics would mean that we loose the benefit of the restructure work in my mind. The pre-defined four categories can help us thanks to the work to describe and delineate between them already done, but if we have our own ~2 categories for example, then we won't have such benefits.

or breaking external links... a pet hate of mine

Certainly looking to avoid that!

just for Z2JH, or JupyterHub as a whole?

I'm very clear that if I invest work in this, I'd like it to be focused on Z2JH without getting burdened by helping the entire JupyterHub org right away in a transition somehow. With this said, I'm currently very positive on systematically nudging us towards a common structure on documentation to be used by new projects and old projects documentation that we rework - i just don't want this z2jh scoped work to get slowed down by org-wide work.

[willingc]

In general, I really like Divio's framework for docs. I could see this to mostly be moving files around and potentially splitting or combining a few markdown files. Having it all in one repo for Z2JH and later moving JupyterHub docs to the same format makes sense.

@consideRatio Having used this framework with two startups in the past year and a half, the biggest difficulty is scoping tutorials vs. How to. They tend to blend over time.

Happy to review as you start moving stuff.

[choldgraf]

I think it's a great idea and happy to review as well. That said I wanted to echo one piece of advice that i remember from the diataxis tutorials: in general it is not recommended to completely rework the documentation in one giant PR. But rather to use the diataxis framework as a guide over the course of multiple actions to update the docs. In our case it might make sense to make a few structural or larger changes in some cases, but we don't need to do it all at once!