Re: [PATCH] Docs: new structure

Jenni Nikolaenko
2022-11-04T13:57:24Z

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