From: Alyssa Ross <alyssa.ross@unikie.com>
To: Jenni N <evgeniia.nikolaenko@unikie.com>
Cc: devel@spectrum-os.org
Subject: Re: [PATCH] Docs: new structure
Date: Thu, 29 Sep 2022 08:58:50 +0000 [thread overview]
Message-ID: <87k05mr1yt.fsf@alyssa.is> (raw)
In-Reply-To: <166436957614.2159633.151682565569021074@atuin.qyliss.net>
[-- Attachment #1: Type: text/plain, Size: 3424 bytes --]
"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.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]
next prev parent reply other threads:[~2022-09-29 8:59 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
2022-09-29 8:58 ` Alyssa Ross [this message]
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=87k05mr1yt.fsf@alyssa.is \
--to=alyssa.ross@unikie.com \
--cc=devel@spectrum-os.org \
--cc=evgeniia.nikolaenko@unikie.com \
/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).