[GarnetFloride]

Diataxis is a great way of thinking about documentation and it really helps organizations get documentation off of the ground.

I generally didn't make separate pages for each type of documentation, they were separate sections.

For example, for a particular feature I would have an explanation at the top so someone looking at it would know what it was for, the audience would be a prospective customer/user trying to determine if they want/need to use it to do a task.

A tutorial section for someone who's never used it before, so very detailed.

A How-to section that has a easy to skim format so if someone is doing something but they can't remember all the steps they can go through it really quick to do the task so they can continue with their work.

The reference section would call out all the options and variables and prerequisites and so on.

For on-prem software the whole install and config section was a tutorial by default because they'd never done it before. A README should have two sections an explanation (what is it and what do you use it for) and a tutorial (how to set it up).

Tutorials are often in a separate section because people expect that but tutorials have an audience that have no experience in the product, the big problem is that the writer often has the curse of knowledge and has a hard time remembering what other people don't know and making sure to add that information in. They need to set up the framework to understand the design philosophy of the product so they can understand the How-tos.

[kaycebasques]

Yes, we also mostly landed on a section approach (tutorial in one section, explanation in another, etc.) versus page approach (tutorial on one page, explanation on another page, etc.). Perhaps the Diataxis site itself should provide guidance on when you might be better off with a section approach versus a page approach, or some other approach entirely. The idea of modes is very subtle. I don't think most Diataxis readers immediately grok it. I think many people assume that the site is recommending a page approach.

What I'm hinting at re: homepages and READMEs is that there's an art and science to index pages (I think of both READMEs and homepages as types of index pages). I'm not convinced that you can boil down index pages to just a mix of explanations, tutorials, references, and guides. I think it's a different type of content that's not really well-represented on the Diataxis map.