look into Diataxis for guidance advice

[NicciPotts]

Feedback from survey

There is a paradigm called Diataxis (https://diataxis.fr/) that I can't recommend highly enough for capturing the key components of good documentation - could there be some how-to guides? Or even a fully worked tutorial using a toy repository?

[NicciPotts]

1. Identify ways to incorporate diataxis to guidance @daffidwilde
2. Examples on how to be a good repo-contributor (how to PR, how to build open-source repo, etc) - focused on why you should care framed as how-tos) @TSGreen

[r-leyshon]

Very curious about this. Just watched this talk at pycon given by the author. I don't think I'm very good at identifying what type of documentation I am writing in all honesty. @daffidwilde as you've used the diataxis rubrik before, what type of documentation do you feel should be in scope for this guidance? My quick take was somewhere like below, but like I said, I struggle to categorise docs in this way:

[daffidwilde]

Based on the conversation we had yesterday, we want the documentation to have some examples (how-to guides or tutorials) and to set out our values (explanation and reference).

I envision a deep-dive into the exemplar project as a tutorial showing what good practice looks like - glossing over why it's important or how to do it. Then we have a handful how-to guides for "open as you go" and "open at the end", how to determine if you can code in the open... small, self-contained pages that we can add to later if necessary.

The content explaining why it's important, what our responsibilities are and so on is already there in the guidance. I think we can add a short page of external links to reference material - more detail on how to do this in a particular language, the NHSX guidance, etc. - but otherwise we are pretty much covered.

[r-leyshon]

@daffidwilde @ethan-moss have I interpreted this issue to be about including some guidance about diataxis in the contributing.md, rather than adapting the website to conform to diataxis guidance? In which case this would be a much smaller job.

For context, I am about to start on the 'never open' section, and am thinking about how to keep the docs focussed.