"Jenni N" <evgeniia.nikolaenko@unikie.com> writes:

>> 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.

Okay, thank you for the very detailed answer!  That's convincing to me —
let's move ahead with your new structure.