From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from atuin.qyliss.net (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id 6A04C1ACD1; Fri, 4 Nov 2022 13:57:24 +0000 (UTC) Received: from atuin.qyliss.net (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id F26491ACCD for ; Fri, 4 Nov 2022 13:57:22 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: Re: [PATCH] Docs: new structure From: "Jenni Nikolaenko" To: devel@spectrum-os.org Date: Fri, 04 Nov 2022 13:57:22 -0000 Message-ID: <166757024292.1913.13612302194626341643@atuin.qyliss.net> In-Reply-To: <20221101121335.7zh7kxcnxyrojdfp@x220> References: <20221101121335.7zh7kxcnxyrojdfp@x220> User-Agent: HyperKitty on https://spectrum-os.org/ Message-ID-Hash: Q2NKYBMLBOFLABY5HWWZVQPDL6DDBFD3 X-Message-ID-Hash: Q2NKYBMLBOFLABY5HWWZVQPDL6DDBFD3 X-MailFrom: evgeniia.nikolaenko@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 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: X-TUID: fiyqQfggA/9g > > This is one of a few sentences that the patch still changes to be > > single-spaced. Fixed. > > Let's wrap these at 70-80 characters too. There's an example in the > > AsciiDoctor documentation of how to do it (looks like it needs > > backslashes at the end of lines): I decided to delete these descriptions as I moved this section under the Development chapter, and it makes no sense. But I added this to our future Working with Documentation section. > > *The* Nix package manager, and *the* Nixpkgs package collection. > > Maybe we could link to them too? Fixed. > > This whole page is excellent, thanks a lot! I am glad to do this! > > testing-patches.adoc is about testing patches submitted by other people, > > so I don't think it makes sense to link to it in this context. Fixed – You can [test patches] subbmited by others. Oh, hell, now I can see the typo here. Ok, hello "patch v4". I will fix it while adding the Writing Documentation section. > > Ideally I'd like it if the documentation didn't assume familiarity with > > b4, because lots of people won't have used it before, it's not too well > > documented, and using it with Spectrum only requires learning a couple > > of commands. So let's try to instead just explain everything about it > > somebody using it with Spectrum would need to know in our documentation? > > If there's missing info about it I can try to expand what we have. Yes, let’s try to expand it. Meanwhile, I changed it to the simple item list and added AsciiDoc there. > > My comments from the previous version still apply here — this [example] > > attribute shouldn't be removed, … > > … and this was also correct before. > > This isn't shell source code, so we shouldn't use this attribute here. > > Spectrum, not Spectrum OS. :) > > Since there's no way to find them in the navigation, and they don't > > have any content or child pages, should we just delete these Diátaxis category pages? > > typo: grinning > > One too many "a"s here — it's "aarch64". All fixed. Sorry for missing it. > > I don't think this last thing is something that an end user is likely to > > want to do — it's really a development convenience. I moved it to the Development chapter, now it is under the Managing VMs section. > > Let's maybe be a bit less specific about what's in the development > > section? These three things are things that we have documented right > > now, but as the documentation fills up these probably won't be the most > > important three things somebody might be looking for. Fixed – Once you are up and running, see [Development] to understand how to work with Spectrum's code and participate in the collaborative development process. > > "makes Nix to trust" is ungrammatical. This should be > > "tells Nix to trust" or "makes Nix trust". Oops! My bad. > > b4 is a development tool, so people don't need to wory about it to > > install Spectrum. And the getting-spectrum.adoc document already > > explains about the binary cache, so I think we should just link to > > getting-spectrum.adoc here. I reorganized it a little bit. Now configuring b4 is in the patches section under the Development chapter. Also, I added a general workflow description. > > "If you have the configuration layer" doesn't really make sense to me. > > Maybe we could say: > > If you need to customise the build, for example to use a vendor kernel, > > you can use a xref:../development/bulid-configuration.adoc[build > > configuration file]. Fixed.