From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on atuin.qyliss.net X-Spam-Level: X-Spam-Status: No, score=-1.1 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.6 Received: from atuin.qyliss.net (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id 36D4080B56; Thu, 29 Sep 2022 08:59:02 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 496) id 5670580AF1; Thu, 29 Sep 2022 08:58:59 +0000 (UTC) Received: from mail-ej1-x631.google.com (mail-ej1-x631.google.com [IPv6:2a00:1450:4864:20::631]) by atuin.qyliss.net (Postfix) with ESMTPS id 7972E80AF0 for ; Thu, 29 Sep 2022 08:58:56 +0000 (UTC) Received: by mail-ej1-x631.google.com with SMTP id b2so1399514eja.6 for ; Thu, 29 Sep 2022 01:58:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=unikie.com; s=google; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:from:to:cc:subject:date; bh=XV+DhEWatDe5iOa0SseoHyd71uJdRPs7dzohXka0bmw=; b=A4SlLcou4Ng6BDUoVI0UTSCjzjLBzGLsvmzv/C0LIrCifO+bwZr6IAcLD9E55rX84U f2r009It5C0JephLhTtx8YLuvsl6jTcvG/Wk5Kbiy/mEDJc7qsXVPqDSBSSitfzrQ3Aj TgOl55f7SsaBhbcL6WYrYwsrWnGq6y9UBdwVDwo3d5TnPRselBBGbQb/ZEmHwgtJbm9R bCMv5pGhwBj9jFKjiMpMqI7lJOLvn7TAMP2Lfhw9v5KeSHZ/35aC7S61l8SgPHLp5m45 f9zUr+ufQLgq6bNjqZmH8RKNd75OKpql1lT+TCTNmE4gyrciDyYGP6FBE/HaoAiwmMIZ zAeg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date; bh=XV+DhEWatDe5iOa0SseoHyd71uJdRPs7dzohXka0bmw=; b=fFAr7zk40fzIE1U1mCs2eY2kTHLeD3HLG9zC/PuMDLm4cpBOzjo2M1e43eDGetloWJ gvU7cptjrM6jd+Fdo0LJF+e49qV9ulsjema218CcFj5MbCFfy4cq4QIRFbq0kBMRGD2G 7aBEfvfs85zpkmEV6otHqpGjEGzCK127qNk65PtJEepic8O14kW2ftxQpPrti7M/TPrf Qi+iROmaT6jbnSuOGVEUSB4V3cmv3v92Q1hEFq3HLFRon4vxqaKpp+7g1NMxBxECfQw9 +GDqGfgDDzYOMCVghko2lEgk0i15qXmfpGkP+++0QbfxBRbeyVEc/pCsG109zeJcFbCS z4GA== X-Gm-Message-State: ACrzQf2My2hsX2hJyMQt8oZtLp+gIzoVbBuEPf4mn0ZvO+5MhgmWGa4z +KkrkHQ5k3Y8wVvO5PTnuYByqvYBf4UzdI/k X-Google-Smtp-Source: AMsMyM4CbsxWcVC3fN5SdcucsH4rHV6f1s521ai/ex7xnFvT4nQy+M+hFDZ04BxFjokW0xkdqV0dkA== X-Received: by 2002:a17:907:1c20:b0:781:c7fc:518e with SMTP id nc32-20020a1709071c2000b00781c7fc518emr1841185ejc.309.1664441935950; Thu, 29 Sep 2022 01:58:55 -0700 (PDT) Received: from x220.qyliss.net (p200300ed673b8e010000000000000004.dip0.t-ipconnect.de. [2003:ed:673b:8e01::4]) by smtp.gmail.com with ESMTPSA id ee10-20020a056402290a00b0045823897230sm915010edb.31.2022.09.29.01.58.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 29 Sep 2022 01:58:54 -0700 (PDT) Received: by x220.qyliss.net (Postfix, from userid 1000) id A4A4D52C; Thu, 29 Sep 2022 08:58:53 +0000 (UTC) From: Alyssa Ross To: Jenni N Subject: Re: [PATCH] Docs: new structure In-Reply-To: <166436957614.2159633.151682565569021074@atuin.qyliss.net> References: <87illjn23a.fsf@alyssa.is> <166436957614.2159633.151682565569021074@atuin.qyliss.net> Date: Thu, 29 Sep 2022 08:58:50 +0000 Message-ID: <87k05mr1yt.fsf@alyssa.is> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Message-ID-Hash: V7OGBQOKG2HYCWLLHCSWPBGFJPUYKYPN X-Message-ID-Hash: V7OGBQOKG2HYCWLLHCSWPBGFJPUYKYPN X-MailFrom: alyssa.ross@unikie.com X-Mailman-Rule-Hits: header-match-devel.spectrum-os.org-0 X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1 CC: devel@spectrum-os.org X-Mailman-Version: 3.3.5 Precedence: list List-Id: Patches and low-level development discussion Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable "Jenni N" writes: >> What did you think about the Di=C3=A1taxis system we were using (well, t= rying >> to use) before? I know we weren't applying it very well =E2=80=94 we de= finitely >> needed top-level categories about the Di=C3=A1taxis ones so that develop= er >> documentation and user documentation weren't mixed together =E2=80=94 bu= t 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 =E2=80=94 you'r= e 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=C3=A1taxis 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=C3=A1taxis 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. > > =D0=A1onsidering all of the above, it seems to me that we can stay on this > path with Di=C3=A1taxis 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 =E2= =80=94 let's move ahead with your new structure. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEH9wgcxqlHM/ARR3h+dvtSFmyccAFAmM1XkwACgkQ+dvtSFmy ccDL5g/9FnMM2Cx+7iUSHbS+noFM9i2z6towyHc9frXAv9CewKklH66GDfAscZm/ JsZd82DKZkjsJd46kEQyNsTpSjFLy6Hd+WXtjr31suKLb7X0zdddzSLrAlRuvcQj SmaX4NEJlRBb0jF+xwbOx/GoZUyTSZ8RFxylsCp1bHQaP/kLxt3A4TwkqHWz7QH/ 3nLrpZwvRLD64ADxF/sUh+WN2X5MYIPvoSRr3PdoxugB+4BdOvLhZ/X/8mpc/i8n jLJ4snT/FK8hiN40Mh5BamcSIUS82ZYZWQERb9k1dw7tgWvRVWQvFRvrhjKMBR+f mO2MVAdo+a5XXRjjGj30H9vy4xT6aREf4fhfJZim7XIFiKhINeDBnjYm3cMBgKgi RmZIySr5tLiMmXv5RQ6FbB0EdNWV9MIGrlBEh8MlgEHCY1Vs+yGZiLuT2FjgOyL2 sr40jelKq+BTJ/+27jl8Pq2mlsA8Zg6vtbKMiDdffhjE0gsb1VUJXnjVBpYSsl6i c2xObzx5CYliuYa7xy+2PtTIlr3sxMfBrit7vTZJxJhEPVZSyAX9/VPeNZ9NfQUA vW4OX3RYAAgnd+aqTGvy4FmgNObYvNJPjHM1J7MDUIRItKvxzTjPMJzZkr51h7lh JrrsTEr9o2sACO3t4yCGgNrq6DPPi8h69InZdltae3iqn13vv0A= =2m+l -----END PGP SIGNATURE----- --=-=-=--