Re: [PATCH] Docs: new structure

["Jenni Nikolaenko" <evgeniia.nikolaenko@unikie.com>]

> > Thank you for organising the AsciiDoc files into subdirectories.  The
> > main Documentation directory was definitely getting a bit unwieldy.
Yes, that is a good rule. Let's stick to it in the future. Also added it to our future Writing Documentation section.

> > The name of the OS is "Spectrum", not "Spectrum OS".
Fixed.

> > Unless you have an agreement otherwise, it's likely that Unikie owns the
> > copyright for these changes, rather than yourself, in which case this
> > would already be covered by the Unikie copyright notice above.  (The
> > copyright notice for myself is there because of the work I did on
> > Spectrum prior to working for Unikie.)
Ok, I get it. Fixed. Let’s just use this one:
// SPDX-FileCopyrightText: 2022 Unikie

> > The double space after the period here was deliberate — some people find
> > it improves readability, and others don't like it, but the reason I've
> > been using it in prose is that it allows text editors to differentiate
> > between the ends of sentences and abbreviations (like "etc."), which
> > means that they can make commands like "move to the next sentence" work
> > accurately even if those abbreviations are used.  Do you think there's a
> > reason we should change?
We decided to use the double space after the period. Also added this rule to our future Writing Documentation section.

> > I haven't seen this description field before.  Where's it used?
:description:--simple attribute (https://asciidoctor.org/docs/asciidoc-recommended-practices/#attribute-groups). It is also good manners rule to have the proper document header.
In practice, this means that if several people are working on a document, then everyone knows what should be approximately described in this section.

> > It's very subtle, but Spectrum is not really derived from NixOS.
> > Rather, the same packaging tool (Nix) and recipes (Nixpkgs) that are
> > used by NixOS are also used by Spectrum.
Old version: Spectrum is a Linux-based system, derived from NixOS
New version: Spectrum is a Linux-based system that uses Nix package manager and Nixpkgs collection of packages.

> > Also, please keep text hard wrapped at 70-80 characters.  (Most editors
> > should be able to do this automatically.)  This makes it easier to pick
> > out specific parts in review, and also makes it easier to read in some
> > editors.  (It doesn't make a difference to the result as rendered in the
> > web browser.)
Fixed in all my sections. Also added this rule to our future Writing Documentation section.

> > This is the /goal/, but is not currently the case.  Maybe we should say
> > "that will make Spectrum unique", or somehow indicate that in another
> > way?  I just wouldn't want anybody to see this in the documentation and
> > then be disappointed to discover that it's not actually (yet) the case.
> > What do you think?
Deleted this sentence “There are several features that make Spectrum OS unique:”.
Now we have only this:
Why Spectrum?
Because user data and applications are managed centrally while remaining isolated…. And also because the host system and isolated environments are managed declaratively and reproducibly using the Nix package manager…
We do not make any promises, but simply say that if you are interested in these things, then you will choose Spectrum.

> > Nice tip.  That's a great way to describe it.
Yay ^_^

> > Hmm, "If you worked" doesn't sound correct to me.  I think it's the
> > wrong tense?  Maybe "you have", if you want it to sound less informal
> > than "you've"?
It was about using simple tenses. Let’s rephrase it to avoid additional issues:
The process of making changes is similar to working on any git repository.

> > Good catch with the commas, thanks.
Yay ^_^

> > If we're telling people where they can ask questions, might also be good
> > to mention the IRC/Matrix channel?  People seem to mostly prefer that
> > for quick questions, since it's realtime.
Added:
For real-time feedback, use IRC/Matrix channel.

> > Hmm, why add explicit numbers here?  They'll be automatically inserted
> > by Asciidoctor, but not writing them manually in the source means that
> > the writer doesn't have to manually renumber things if they add
> > something in the middle of the list of move things around?
Fixed.

> > If the only comparison we draw to other systems is that Spectrum is
> > trying to be easier to use, I'm worried that would give the impression
> > that that's the only interesting thing about Spectrum, and e.g. put
> > people off that don't find what they're currently using to be too hard
> > to use.  e.g. other reasons people might want to use Spectrum are that
> > we will have wider hardware support through the ARM port Unikie is
> > working on, and that we have security features other similar systems
> > don't have (although we can't just claim to be *more* secure, since
> > there will be other things they do better than us).  But I also
> > understand that this is just a short introductory sentence, so we can't
> > go into too much detail.
Fixed. Let's rephrase it:
Spectrum is an open-source project that aims to create a computer operating system, based on the principle of security by compartmentalization, that has a lower barrier to entry and is easy to use and maintain.

> > This is quite similar to the sentence at the start of this page.  Maybe
> > it doesn't make sense (yet) to try to distinguish Spectrum the project
> > from Spectrum the operating system?
Yes, you are right. It was not a very good idea to use the terms project and OS. I completely rewrote this section, so it is more like a map of the whole Spectrum Docs.

> > The information on this page feels very similar to the information on
> > the "Getting Spectrum" page.  Do you think we need both?
Fixed. I updated this page and added there the list of steps.