Re: [PATCH] Docs: new structure

Jenni N
2022-09-28T12:52:59Z

> What did you think about the Diátaxis system we were using (well, trying
> to use) before? I know we weren't applying it very well — we definitely
> needed top-level categories about the Diátaxis ones so that developer
> documentation and user documentation weren't mixed together — but I
> thought maybe it would still make sense to separate
> tutorials/how-to/reference/explanation inside those top-level
> categories. If you don't think it's helpful that's fine — you're the
> expert! But it was something that was recently called out to me by
> somebody following the project as a change they were pleased with, so I
> wanted to check.

It is a fact that most developers don't read everything on the page. As soon as they find a site with documentation they immediately use the search box. If the search engine is bad, then they have to search by hand, only in this case they begin to expand all the nested sections and read the headings.

As I see it, Diátaxis is about how to organize documentation and how to give readers better docs in theory. It must solve the problem of structure. It is not our case, so we can ignore it.

What does the problem with structure mean? It is when the documentation is not understandable. It might be not understandable for different reasons, the main of which--you do not know who exactly your readers are and what information they will be looking for. So, you put everything in four large boxes with very obvious inscriptions tutorials/how-to/reference/explanation. In my humble opinion, we know well who our readers are and what information they will be looking for.

If you ask me, what good documentation is, I would answer, that it is the documentation that exists and is well maintained. All of this means that it is also understandable to the people reading it. Moreover, understandable for people who are going to create new sections in it. We are doing open-source documentation, which means that a huge number of people will participate in this project. We do not know what their background is or how familiar they are with the Diátaxis system.

Ideally, documentation should be separated into user documentation and developer documentation. But at the moment we have only developers and it is not known when the first users will be. More likely that users are just the same developers, the main difference is that they have not send a patch yet.
The developer performs very specific steps: installation, configuration, development, and sending a patch. It turns out that we know our reader and we know what exactly is needed. If some mate needs to install and configure the system, he/she immediately sees the words Installation and Development. No frustration.

Сonsidering all of the above, it seems to me that we can stay on this path with Diátaxis but in the future, when there are more and more pages and people, the documentation will turn into a mixture. I think we can try something new. If the structure I proposed seems not very sutable, I am open to discuss this again. I will be glad to hear any of your decisions.