From: "Jenni N" <evgeniia.nikolaenko@unikie.com>
To: devel@spectrum-os.org
Subject: Re: [PATCH] Docs: new structure
Date: Wed, 28 Sep 2022 12:52:56 -0000 [thread overview]
Message-ID: <166436957614.2159633.151682565569021074@atuin.qyliss.net> (raw)
In-Reply-To: <87illjn23a.fsf@alyssa.is>
> 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.
next prev parent reply other threads:[~2022-09-28 12:52 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-09-06 13:55 Jenni Nikolaenko
2022-09-19 9:30 ` Alyssa Ross
2022-09-28 12:52 ` Jenni N [this message]
2022-09-29 8:58 ` Alyssa Ross
2022-10-28 11:22 ` Jenni Nikolaenko
[not found] <RE: [PATCH] Docs: new structure>
2022-10-28 11:05 ` Jenni Nikolaenko
2022-10-28 11:24 ` Jenni Nikolaenko
2022-11-01 12:14 ` Alyssa Ross
2022-11-01 12:13 ` Alyssa Ross
2022-11-04 13:57 ` Jenni Nikolaenko
2022-11-08 9:03 ` Alyssa Ross
2022-11-08 15:05 ` Jenni Nikolaenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=166436957614.2159633.151682565569021074@atuin.qyliss.net \
--to=evgeniia.nikolaenko@unikie.com \
--cc=devel@spectrum-os.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://spectrum-os.org/git/crosvm
https://spectrum-os.org/git/doc
https://spectrum-os.org/git/mktuntap
https://spectrum-os.org/git/nixpkgs
https://spectrum-os.org/git/spectrum
https://spectrum-os.org/git/ucspi-vsock
https://spectrum-os.org/git/www
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).