Refer to diataxis in PR Checklist

[lukruh]

Mention the diataxis principles in the PR checklist and link to diataxis.fr

[bouweandela]

Documentation is one of the items in the checklist, so I would recommend we update our guidelines for contributing documentation that are linked from the checklist:
https://docs.esmvaltool.org/en/latest/community/code_documentation.html#documentation
https://docs.esmvaltool.org/projects/ESMValCore/en/latest/contributing.html#documentation

[katjaweigel]

Diataxis: https://diataxis.fr/
What is not clear to me, is if the aim are four seperated parts, the way tutorial and documentation are separated at the moment, or if we should update any documentation page and split it into the tree remaining categories (How-to guides, References, Explanation) and mark, which they belong to? Somehow I would at least like to keep them connected: It either through links, but maybe keeping all categories on a page starting with first How-to guides and later Explanation and last References (for both) seems to be more easy to implement to me? (@ehogan ?)

[katjaweigel]

Should we add links into the docu to highlight relevant parts of the tutorial?

[ehogan]

Diataxis: https://diataxis.fr/ What is not clear to me, is if the aim are four seperated parts, the way tutorial and documentation are separated at the moment, or if we should update any documentation page and split it into the tree remaining categories (How-to guides, References, Explanation) and mark, which they belong to? Somehow I would at least like to keep them connected: It either through links, but maybe keeping all categories on a page starting with first How-to guides and later Explanation and last References (for both) seems to be more easy to implement to me? (@ehogan ?)

@katjaweigel Yes, the expectation is that pages related to a specific topic stay connected via links. Diátaxis suggests that documentation is organised by the needs of the users, so this:

How-to guides:
  How-to do thing 1
Reference materials:
  Facts about thing 1
Explanations:
  Why thing 1 is important

is preferred over:

Thing 1:
  How-to guide: How-to do thing 1
  Reference material: Facts about thing 1
  Explanation: Why thing 1 is important

I see no reason not to make changes iteratively. For example, we could start by making changes that follow the second layout above, then move later to the first layout.

The idea is that the user will know what sort of information they are looking for. If the user is trying to complete specific task, they know they will find what they need in the "How-to guides" section of the documentation.

Also, I will be discussing the tutorial more at the workshop tomorrow morning 👍

Does that answer your question? Happy to jump into a different room if you'd like to chat more? 😊

[katjaweigel]

Thanks for your answer @ehogan ! Although I see the point, if one only wants to get the "how to", I'm a bit worried, that with a total split the Reference material and the Explanations will loose importance. Beeing used to scientific publications/ books for me the it would feel normal to have one topic in the order:
Explanation -> How to... -> References (this is how many recipe descriptions are written at the moment, e.g. https://docs.esmvaltool.org/en/latest/recipes/recipe_diurnal_temperature_index.html)
So one docu page about a recipe first write what is does (including the short form/link to the references) and then how to use it.
( Explanation as one/few text block, which one can easily jump over if known/ not interesting e.g.:
This recipe plots fig 1-3 and 5 from the paper of XXX et al. which deals with the evaluations of ESMs regarding some process important for ...
Following by the How to block with variables used, options, data sets often as code blocks
and References + Example figures in the end)
It would be fine for me, to have the "How to" first, but I'm afraid if we split the "How to" and "Explanations" fewer people will read the explanations and people will take less care to write them? I would also not be sure, if example figures would belong to "How to" or Explanations or if we would need to duplicate them?

[ehogan]

Ah, I hadn't considered the recipe documentation specifically. Perhaps the recipe documentation (since it follows a well established template) could be left as it is? But perhaps all the recipe documentation could exist under "Reference materials", since it provides facts and figures about the recipes?

Generally speaking, I would aim to avoid duplicating both documentation and code!

[katjaweigel]

For recipes (which is what I often look at/sometimes write, that is why this came to my mind first) to still adapt parts of the concept of diataxis, I would rather keep things together but mark clearly, if they belong to "How to"; "Explanation" or "References" (maybe wit different colors/ boxes ) at least for the recipe descriptions?
I'd assume a user that is interested in a certain recipe want to know what it does and how, users, who know the "what" can skip reading the part and users who notice while reading "what" that this is not what they need will never read on to "how". The example plots are helpful for both users interested in "what" and "how" and only few people will ever read the references but they have to be there for the few who cares/ want to read further.)

[ehogan]

That makes sense! Updating the recipe documentation template to reflect this would be great! 🥳

[lukruh]

I agree on keeping the individual recipe documentation pages as such. I'd also consider them as part of "References". Explaining certain options or figure etc. does not necessarily make the whole section an explanation. In case of recipes, the corresponding papers could be the explanation. For step by step instructions, it might make sense to create separate how to pages in some cases. I.e. how to setup and use the CDS-API. That makes it easy to link the page from multiple recipes as a prerequisite and requires only one page to be updated if the process changes.