patches and low-level development discussion
 help / color / mirror / code / Atom feed
* [PATCH] Docs: new structure
       [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:13   ` Alyssa Ross
  0 siblings, 2 replies; 12+ messages in thread
From: Jenni Nikolaenko @ 2022-10-28 11:05 UTC (permalink / raw)
  To: devel; +Cc: Jenni Nikolaenko

Create separate folders for new parent pages, update Introduction page,
remove a and the articles from titles, quick check text for simple english

Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
---
 Documentation/{ => about}/architecture.adoc   | 20 ++++---
 Documentation/about/index.adoc                | 30 +++++++++++
 Documentation/building-documentation.adoc     | 52 ------------------
 .../decisions/001-host-update-mechanism.adoc  |  4 +-
 .../decisions/002-install-options.adoc        |  4 +-
 Documentation/decisions/003-partitioning.adoc |  2 +-
 .../004-data-at-rest-encryption.adoc          |  4 +-
 .../005-virtual-machine-monitor.adoc          |  2 +-
 .../decisions/006-drivers-on-host.adoc        |  2 +-
 .../decisions/007-usb-virtual-machines.adoc   |  2 +-
 ...008-inter-vm-communication-mechanisms.adoc |  2 +-
 Documentation/decisions/index.adoc            |  2 +-
 .../build-configuration.adoc                  | 13 +++--
 .../development/building-documentation.adoc   | 53 +++++++++++++++++++
 .../{ => development}/debugging.adoc          | 12 ++---
 .../{ => development}/first-patch.adoc        | 32 +++++------
 Documentation/development/index.adoc          | 31 +++++++++++
 Documentation/{ => development}/replying.adoc | 13 ++---
 .../{ => development}/reviewing-patches.adoc  |  4 +-
 .../{ => development}/testing-patches.adoc    | 34 ++++++------
 .../{ => development}/uuid-reference.adoc     |  5 +-
 Documentation/explanation.adoc                |  3 +-
 .../{ => getting-started}/creating-vms.adoc   |  2 +-
 Documentation/getting-started/index.adoc      | 14 +++++
 .../{ => getting-started}/running-vms.adoc    |  2 +-
 .../getting-started/user-partition.adoc       | 16 ++++++
 Documentation/how-to.adoc                     |  1 +
 Documentation/index.adoc                      | 29 ++++++++--
 Documentation/{ => installation}/b4.adoc      |  5 +-
 .../{ => installation}/binary-cache.adoc      | 18 ++++---
 .../{ => installation}/getting-spectrum.adoc  | 14 ++---
 Documentation/installation/index.adoc         | 26 +++++++++
 Documentation/reference.adoc                  |  3 +-
 Documentation/tutorials.adoc                  |  3 +-
 Documentation/user-partition.adoc             | 12 -----
 35 files changed, 302 insertions(+), 169 deletions(-)
 rename Documentation/{ => about}/architecture.adoc (84%)
 create mode 100644 Documentation/about/index.adoc
 delete mode 100644 Documentation/building-documentation.adoc
 rename Documentation/{ => development}/build-configuration.adoc (73%)
 create mode 100644 Documentation/development/building-documentation.adoc
 rename Documentation/{ => development}/debugging.adoc (79%)
 rename Documentation/{ => development}/first-patch.adoc (80%)
 create mode 100644 Documentation/development/index.adoc
 rename Documentation/{ => development}/replying.adoc (68%)
 rename Documentation/{ => development}/reviewing-patches.adoc (88%)
 rename Documentation/{ => development}/testing-patches.adoc (81%)
 rename Documentation/{ => development}/uuid-reference.adoc (97%)
 rename Documentation/{ => getting-started}/creating-vms.adoc (98%)
 create mode 100644 Documentation/getting-started/index.adoc
 rename Documentation/{ => getting-started}/running-vms.adoc (93%)
 create mode 100644 Documentation/getting-started/user-partition.adoc
 rename Documentation/{ => installation}/b4.adoc (93%)
 rename Documentation/{ => installation}/binary-cache.adoc (80%)
 rename Documentation/{ => installation}/getting-spectrum.adoc (82%)
 create mode 100644 Documentation/installation/index.adoc
 delete mode 100644 Documentation/user-partition.adoc

diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc
similarity index 84%
rename from Documentation/architecture.adoc
rename to Documentation/about/architecture.adoc
index 1c4307b..c1af320 100644
--- a/Documentation/architecture.adoc
+++ b/Documentation/about/architecture.adoc
@@ -1,17 +1,15 @@
 = Architecture
-:page-parent: Explanation
+:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-== Introduction
+Spectrum is based on the principle of security by compartmentalization.
 
-Spectrum is based on the principle of security by
-compartmentalization.  The high level stack is illustrated in the
-following diagram:
+The high level stack is illustrated in the following diagram:
 
-image::diagrams/stack.svg[]
+image::../diagrams/stack.svg[]
 
 The default set of virtual machines includes two application VMs,
 _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web
@@ -26,7 +24,7 @@ https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant
 decisions] are xref:decisions/index.adoc[recorded] as lightweight
 https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs].
 
-== The Spectrum host system
+== Spectrum Host System
 
 Compartmentalization is implemented using
 https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines.
@@ -35,7 +33,7 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual
 Machine] (KVM) to provide lightweight, hardware-accelerated VMs.
 
 While Linux (including KVM) is portable between many hardware architectures,
-cloud-hypervisor supports only x86_64 and aarch64.  Spectrum currently only
+cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only
 works on x86_64, but aarch64 support is in development.
 
 https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service
@@ -44,7 +42,7 @@ and service scripts.
 
 https://wayland.freedesktop.org/[Wayland] is used for window management and
 display.  The Wayland architecture is well documented
-https://wayland.freedesktop.org/architecture.html[here].  The host provides only
+https://wayland.freedesktop.org/architecture.html[here]. The host provides only
 a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used
 for interacting with VM consoles.  In future it will be possible for application
 VMs to display windows on the single Wayland compositor on the host system,
@@ -57,7 +55,7 @@ https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion
 and security hardening on memory allocation].  Kernel hardening will be
 investigated in future.
 
-== Exploring the Spectrum dependency tree
+== Spectrum Dependency Tree
 
 For a detailed, interactive view of dependencies, use
 https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository:
@@ -67,4 +65,4 @@ https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository:
 nix-build img/live -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree
 
 https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image
-interactive analysis with nix-tree]
+interactive analysis with nix-tree].
diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc
new file mode 100644
index 0000000..9e2a47e
--- /dev/null
+++ b/Documentation/about/index.adoc
@@ -0,0 +1,30 @@
+= About Spectrum
+:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.
+:page-nav_order: 1
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Spectrum is a Linux-based system that uses Nix package manager and Nixpkgs
+collection of packages.
+
+This gives an actively-developed base with good
+hardware support, powerful and optimised compartmentalization primitives in
+KVM, and the reproducible packaging and configuration system that is important
+for a maintainable compartmentalized system.
+
+== Why Spectrum
+
+* User data and applications are managed centrally while remaining isolated.
+That means that the system can be backed up and managed as a whole, rather than
+mixed up in several dozen VMs.
+
+* The host system and isolated environments are managed declaratively and
+reproducibly using the Nix package manager.
+This can save the user the burden of maintaining many different virtual
+computers, allowing finer-grained resource access controls and making it
+possible to verify the software running across all environments.
+
+TIP: If you are interested in why we do something _this_ way instead of _that_
+way, see xref:../decisions/index.adoc[Architecture Decision Records].
diff --git a/Documentation/building-documentation.adoc b/Documentation/building-documentation.adoc
deleted file mode 100644
index b491105..0000000
--- a/Documentation/building-documentation.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-= Building the Documentation
-:page-parent: Tutorials
-
-// SPDX-FileCopyrightText: 2022 Unikie
-// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
-
-This tutorial assumes that you have https://nixos.org/[Nix] installed.
-You may also want to xref:binary-cache.adoc[configure the Spectrum
-binary cache], to avoid having to wait for dependencies to compile on
-your local system.
-
-1. Get a copy of the Spectrum source code:
-+
-[source,shell]
-----
-git clone https://spectrum-os.org/git/spectrum
-----
-2. Enter the documentation directory:
-+
-[source,shell]
-----
-cd spectrum/Documentation
-----
-3. Enter the development environment:
-+
-[source,shell]
-----
-nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz
-----
-4. In the development shell, do an initial build of the documentation
-site:
-+
-[source,shell]
-----
-scripts/build.sh
-----
-5. Run a development server for previewing changes locally:
-+
-[source,shell]
-----
-jekyll serve
-----
-+
-This will serve a local copy of the documentation at http://localhost:4000/.
-+
-IMPORTANT: Jekyll doesn't handle rendering of the draw.io diagrams, so
-if you modify any of those, or add new ones, you'll have to run
-`scripts/build.sh` again to do a full rebuild of the site.
-
-Once you've made your changes to the documentation, see
-xref:first-patch.adoc[Sending Your First Patch] for information
-about how to submit them for review.
diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc
index 574deb4..39f9f28 100644
--- a/Documentation/decisions/001-host-update-mechanism.adoc
+++ b/Documentation/decisions/001-host-update-mechanism.adoc
@@ -1,6 +1,6 @@
 = 001 Host Update Mechanism
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -11,7 +11,7 @@ Proposed
 
 == Context
 
-Spectrum currently has no implementation for software update. The host --
+Spectrum currently has no implementation for software update.  The host --
 consisting of the Linux kernel, KVM, cloud-hypervisor and minimal user space
 tools -- will require software updates to support feature development and
 security fixes.
diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc
index 4412b53..4a745eb 100644
--- a/Documentation/decisions/002-install-options.adoc
+++ b/Documentation/decisions/002-install-options.adoc
@@ -1,6 +1,6 @@
-= 002 Install options
+= 002 Install Options
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc
index 8494ea4..a13b8cc 100644
--- a/Documentation/decisions/003-partitioning.adoc
+++ b/Documentation/decisions/003-partitioning.adoc
@@ -1,6 +1,6 @@
 = 003 Partitioning
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc
index 26fe273..5b0f518 100644
--- a/Documentation/decisions/004-data-at-rest-encryption.adoc
+++ b/Documentation/decisions/004-data-at-rest-encryption.adoc
@@ -1,6 +1,6 @@
 = 004 Data at Rest Encryption
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -20,5 +20,5 @@ User data is encrypted.
 == Consequences
 
 Spectrum needs to come with enough software to get the encryption key
-via different methods (password, usb, fido, etc.)  Can we use dm-crypt
+via different methods (password, usb, fido, etc.).  Can we use dm-crypt
 for everything instead of LUKS?
diff --git a/Documentation/decisions/005-virtual-machine-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc
index db81c72..df1b501 100644
--- a/Documentation/decisions/005-virtual-machine-monitor.adoc
+++ b/Documentation/decisions/005-virtual-machine-monitor.adoc
@@ -1,6 +1,6 @@
 = 005 Virtual Machine Monitor
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc
index 872044e..b92d863 100644
--- a/Documentation/decisions/006-drivers-on-host.adoc
+++ b/Documentation/decisions/006-drivers-on-host.adoc
@@ -1,6 +1,6 @@
 = 006 Drivers on Host
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc
index 3bdf78b..d832691 100644
--- a/Documentation/decisions/007-usb-virtual-machines.adoc
+++ b/Documentation/decisions/007-usb-virtual-machines.adoc
@@ -1,6 +1,6 @@
 = 007 USB Virtual Machine
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
index a1b7d49..c1e5b87 100644
--- a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
+++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
@@ -1,6 +1,6 @@
 = 008 Inter-VM Communication Mechanisms
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc
index 772f382..a022239 100644
--- a/Documentation/decisions/index.adoc
+++ b/Documentation/decisions/index.adoc
@@ -1,6 +1,6 @@
 = Architecture Decision Records
 :page-has_children: true
-:page-parent: Explanation
+:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/build-configuration.adoc b/Documentation/development/build-configuration.adoc
similarity index 73%
rename from Documentation/build-configuration.adoc
rename to Documentation/development/build-configuration.adoc
index b89575f..c9a8c99 100644
--- a/Documentation/build-configuration.adoc
+++ b/Documentation/development/build-configuration.adoc
@@ -1,19 +1,22 @@
 = Configuring the Build
-:page-parent: How-to Guides
+:page-parent: Development
+:page-nav_order: 1
 :example-caption: Test
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
 Some aspects of a Spectrum build can be customised using a build
-configuration file.  By default, this configuration file should be
-called config.nix and located in the root of the Spectrum source tree,
-but this can be overridden by setting `spectrum-config` in the
+configuration file.
+
+By default, this configuration file should be called config.nix and located in
+the root of the Spectrum source tree, but this can be overridden by setting
+`spectrum-config` in the
 https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PATH[NIX_PATH]
 to the path of the configuration file.
 
 The configuration file should contain an attribute set.  The only
-currently allowed attribute name is `pkgs`, which allows using a
+currently allowed attribute name is `pkgs`. It allows using a
 custom Nixpkgs to evaluate Spectrum.
 
 .config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition[Nixpkgs overlay]
diff --git a/Documentation/development/building-documentation.adoc b/Documentation/development/building-documentation.adoc
new file mode 100644
index 0000000..d83c343
--- /dev/null
+++ b/Documentation/development/building-documentation.adoc
@@ -0,0 +1,53 @@
+= Building Documentation
+:page-parent: Development
+:page-nav_order: 4
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Make sure you have https://nixos.org/[Nix] installed.
+You may also want to xref:binary-cache.adoc[configure the Spectrum
+binary cache], to avoid having to wait for dependencies to compile on
+your local system.
+
+. Get a copy of the Spectrum source code:
++
+[source,shell]
+----
+git clone https://spectrum-os.org/git/spectrum
+----
+. Enter the documentation directory:
++
+[source,shell]
+----
+cd spectrum/Documentation
+----
+. Enter the development environment:
++
+[source,shell]
+----
+nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz
+----
+. In the development shell, do an initial build of the documentation
+site:
++
+[source,shell]
+----
+scripts/build.sh
+----
+. Run a development server for previewing changes locally:
++
+[source,shell]
+----
+jekyll serve
+----
++
+This will serve a local copy of the documentation at http://localhost:4000/.
++
+IMPORTANT: Jekyll does not handle rendering of the draw.io diagrams. If you
+modify any of those, or add new ones, run `scripts/build.sh` again to do a full
+rebuild of the site.
+
+After making changes to the documentation, see
+xref:first-patch.adoc[Working with Patches] for information
+on how to submit your changes for review.
diff --git a/Documentation/debugging.adoc b/Documentation/development/debugging.adoc
similarity index 79%
rename from Documentation/debugging.adoc
rename to Documentation/development/debugging.adoc
index 3871a7c..d342294 100644
--- a/Documentation/debugging.adoc
+++ b/Documentation/development/debugging.adoc
@@ -1,7 +1,6 @@
-= Debugging Spectrum
-:page-parent: Explanation
-:toc:
-:toclevels: 1
+= Debugging
+:page-parent: Development
+:page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -9,8 +8,9 @@
 == Extracting core dumps when running Spectrum in a VM
 
 When using a VM to run the Spectrum host system, a special mechanism
-is available to enable easy introspection of core files.  When a
-program on the Spectrum host system dumps core, the system will
+is available to enable easy introspection of core files.
+
+When a program on the Spectrum host system dumps core, the system will
 attempt to upload the core file to _its_ host (i.e. the system running
 Spectrum in a VM) using the vsock(7) protocol, on port 1129271877.
 
diff --git a/Documentation/first-patch.adoc b/Documentation/development/first-patch.adoc
similarity index 80%
rename from Documentation/first-patch.adoc
rename to Documentation/development/first-patch.adoc
index 30672b9..cf19b37 100644
--- a/Documentation/first-patch.adoc
+++ b/Documentation/development/first-patch.adoc
@@ -1,11 +1,11 @@
-= Sending Your First Patch
-:page-parent: Tutorials
+= Working with Patches
+:page-parent: Development
+:page-nav_order: 1
+:page-has_children: true
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-== Prerequisites
-
 This tutorial assumes that you already have basic
 https://git-scm.com/[git] experience.
 
@@ -14,19 +14,18 @@ https://spectrum-os.org/git/[Spectrum source tree].  You'll also need
 to have configured `git send-email` — a guide for this can be found at
 https://git-send-email.io/.
 
-== Making your changes
+== Making Changes
 
-If you've worked on any git repository before, the process for making
-your changes will probably be very familiar.
+The process of making changes is similar to working on any git repository.
 
-1. Create a branch for your changes:
+. Create a branch for your changes:
 +
 [source,shell]
 ----
 git checkout -b fix-docs # for example
 ----
-2. Make changes in your editor.
-3. Stage and commit your changes:
+. Make changes in your editor.
+. Stage and commit your changes:
 +
 [source,shell]
 ----
@@ -39,7 +38,7 @@ indicates your acceptance of the
 https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's
 Certificate of Origin], which is mandatory for Spectrum patches.
 
-== Submitting changes
+== Submitting Changes
 
 Once you're happy with how the commits on your branch look, run:
 
@@ -64,13 +63,14 @@ message that will be sent before all of your patches.
 
 Once your patch has been submitted, wait for it to be reviewed.
 Feedback, if any, will be sent as email replies to your submitted
-patch.  You can respond to feedback in your mail client.  Please use
-the Reply All button to ensure that your messages are sent to the
+patch.  You can respond to feedback in your mail client.
+
+Use the *Reply All* button to sent your messages to the
 mailing list as well as to the person who sent the feedback.
 
-If you need to make changes to your patch, and submit a new version,
+If you need to make changes to your patch and submit a new version,
 use https://git-rebase.io/[`git rebase`] to create a new version of
-your patch(es), and submit it like this:
+your patch(es) and then submit it like this:
 
 [source,shell]
 ----
@@ -81,7 +81,7 @@ The added `-v2` flag indicates that this is version two of your
 patch set.  If your patches require more rounds of changes, submit
 subsequent rounds with `-v3`, `-v4`, etc. as appropriate.
 
-If you'd like to describe what has changed from the previous version
+If you would like to describe what has changed from the previous version
 of your patches, you can do so in a xref:cover-letter[cover letter]
 as described above.
 
diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
new file mode 100644
index 0000000..1fe4d8b
--- /dev/null
+++ b/Documentation/development/index.adoc
@@ -0,0 +1,31 @@
+= Development
+:description: Development progress, general development practices
+:page-nav_order: 4
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Spectrum is free software, currently under active development.
+
+If you made changes in a source code,
+https://spectrum-os.org/installation/getting-spectrum.html#building-an-installer[rebuild Spectrum],
+xref:../development/testing-patches.adoc[test your patch] and
+then https://spectrum-os.org/development/first-patch.html#submitting-changes[submit your changes for review].
+
+== Developer Setup
+
+Before starting, make sure you are familiar with
+https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] and the
+https://nixos.org/manual/nix/stable/introduction.html[Nix package manager].
+
+== Mailing Lists
+
+The Spectrum project runs several
+https://spectrum-os.org/mailman3/lists/?all-lists[mailing lists] on which you
+can ask your questions or help other people with the questions they have.  All
+the Spectrum developers as well as many long time Linux and Spectrum users are
+on the lists.
+
+For real-time feedback, use
+https://spectrum-os.org/participating.html#irc[IRC/Matrix channel].
diff --git a/Documentation/replying.adoc b/Documentation/development/replying.adoc
similarity index 68%
rename from Documentation/replying.adoc
rename to Documentation/development/replying.adoc
index bb8e31a..a1ad394 100644
--- a/Documentation/replying.adoc
+++ b/Documentation/development/replying.adoc
@@ -1,5 +1,7 @@
 = Replying to Messages in the Mailing List Archives
-:page-parent: Tutorials
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -9,14 +11,13 @@ https://spectrum-os.org/participating.html#mailing-lists[mailing
 lists].
 
 Make sure to Reply All when replying to messages, so that the message
-is sent to the mailing list and not just to the person you're
-replying to.
+is sent to the mailing list and not just to the person you reply to.
 
 == Getting a copy of a message
 
-You may want to reply to a mailing list message that you don't have a
-copy of in your mail client, because you aren't subscribed to the
-list, or because you subscribed after the message was sent.
+You may want to reply to a mailing list message that you do not have a
+copy of in your mail client, because you are not subscribed to the
+list or because you subscribed after the message was sent.
 
 To do this, find the message you want to reply to in the
 https://spectrum-os.org/lists/archives[public-inbox list archives],
diff --git a/Documentation/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc
similarity index 88%
rename from Documentation/reviewing-patches.adoc
rename to Documentation/development/reviewing-patches.adoc
index 63ff24e..ba47f25 100644
--- a/Documentation/reviewing-patches.adoc
+++ b/Documentation/development/reviewing-patches.adoc
@@ -1,5 +1,7 @@
 = Reviewing Patches
-:page-parent: How-to Guides
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc
similarity index 81%
rename from Documentation/testing-patches.adoc
rename to Documentation/development/testing-patches.adoc
index 743cd6e..600cf0f 100644
--- a/Documentation/testing-patches.adoc
+++ b/Documentation/development/testing-patches.adoc
@@ -1,5 +1,7 @@
 = Testing Patches
-:page-parent: How-to Guides
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
@@ -9,7 +11,7 @@ Potential changes to Spectrum are posted to and discussed on the
 https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org]
 mailing list.
 
-== Apply the patch
+== Apply Patch
 
 . Find the patch series you want to test on
   https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox].
@@ -28,35 +30,31 @@ of the Spectrum root's nix-shell, which allows you to skip this step.
   with the patch's Message-Id to download all the patches in the
   series into a file.
 +
-[example]
 [source,shell]
 ----
 b4 am 20220511092352.70E54C980@atuin.qyliss.net
 ----
-
-. b4 will indicate the file name it has downloaded the patches into
-  with a line like:
+b4 will indicate the file name it has downloaded the patches into with a line
+like:
 +
-[example]
-[listing]
+[source,shell]
+----
 Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
+----
+. Run `git am` on that file to apply the patches. For example:
 +
-Run `git am` on that file to apply the patches, for example:
-+
-[example]
 [source,shell]
 ----
 git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
 ----
 
-== Post your test results
+== Post Your Results
 
-When you've tested a patch, it's really helpful to
+When you tested a patch, it is helpful to
 xref:replying.adoc[reply] with your test results.
 
-If the patch worked for you, please reply to it and include a line
-like the following, separated from any reply text:
-
+If the patch worked for you, please reply to it and include a line like the following, separated from any reply text:
+[source,shell]
 ----
 Tested-by: John Smith <john@example.com>
 ----
@@ -66,10 +64,10 @@ patch replies will be automatically included in the commit message
 when a patch is applied.
 
 It's also helpful to explain in your reply how you tested the patch,
-but you don't have to if it's obvious.  (For example, if a patch is
+but you don't have to if it's obvious.  For example, if a patch is
 supposed to fix a bug, and you verified that after applying the patch
 the bug is fixed, just the Tested-by line on its own is enough to
-indicate that.)
+indicate that.
 
 If you found an issue with the patch, do not include a Tested-by line,
 and instead reply to the patch explaining what you tested, what you
diff --git a/Documentation/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc
similarity index 97%
rename from Documentation/uuid-reference.adoc
rename to Documentation/development/uuid-reference.adoc
index 4b0b481..61c602f 100644
--- a/Documentation/uuid-reference.adoc
+++ b/Documentation/development/uuid-reference.adoc
@@ -1,7 +1,8 @@
 = UUID Reference
-:page-parent: Reference
+:page-parent: Development
 :toc: preamble
 :toclevels: 1
+:page-nav_order: 5
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -40,7 +41,7 @@ xref:user-partition.adoc[Spectrum user partition].
 
 === `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e`
 
-https://github.com/endlessm/eos-installer["eosimages"] partition on the 
+https://github.com/endlessm/eos-installer["eosimages"] partition on the
 Spectrum combined live system / installer image.
 
 == Combined Image Partition IDs
diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc
index b39cc6d..f682129 100644
--- a/Documentation/explanation.adoc
+++ b/Documentation/explanation.adoc
@@ -1,6 +1,5 @@
 = Explanation
-:page-has_children: true
-:page-nav_order: 4
+:page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc
similarity index 98%
rename from Documentation/creating-vms.adoc
rename to Documentation/getting-started/creating-vms.adoc
index d967098..e06be85 100644
--- a/Documentation/creating-vms.adoc
+++ b/Documentation/getting-started/creating-vms.adoc
@@ -1,5 +1,5 @@
 = Creating VMs
-:page-parent: Reference
+:page-parent: Getting Started
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc
new file mode 100644
index 0000000..639e0a6
--- /dev/null
+++ b/Documentation/getting-started/index.adoc
@@ -0,0 +1,14 @@
+= Getting Started
+:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). Ready to get started with Spectrum OS? After installing you can create VMs and then configure each one.
+:page-nav_order: 3
+:page-has_children: true
+:page-has_toc: false
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Ready to get started with Spectrum? Here is what you can do next:
+
+* xref:../getting-started/creating-vms.adoc[Create your own VM] to use others applications.
+* xref:../getting-started/running-vms.adoc[Start some applications].
+* If needed, xref:../getting-started/user-partition.adoc[change the user partition type].
diff --git a/Documentation/running-vms.adoc b/Documentation/getting-started/running-vms.adoc
similarity index 93%
rename from Documentation/running-vms.adoc
rename to Documentation/getting-started/running-vms.adoc
index d0d3f99..9073e3c 100644
--- a/Documentation/running-vms.adoc
+++ b/Documentation/getting-started/running-vms.adoc
@@ -1,5 +1,5 @@
 = Running VMs
-:page-parent: Reference
+:page-parent: Getting Started
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/getting-started/user-partition.adoc b/Documentation/getting-started/user-partition.adoc
new file mode 100644
index 0000000..7c142b8
--- /dev/null
+++ b/Documentation/getting-started/user-partition.adoc
@@ -0,0 +1,16 @@
+= User Partition
+:page-parent: Getting Started
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+The Spectrum host system is immutable, so configuration and user data
+lives on a separate partition.
+
+The host system discovers the user
+partition by looking for the special partition type
+`9293e1ff-cee4-4658-88be-898ec863944f`.
+
+This behavior can be overridden with the `ext` parameter on the host's kernel
+command line, which works in a similar way to the standard Linux `root`
+parameter.
diff --git a/Documentation/how-to.adoc b/Documentation/how-to.adoc
index f43fa13..98cc842 100644
--- a/Documentation/how-to.adoc
+++ b/Documentation/how-to.adoc
@@ -1,4 +1,5 @@
 = How-to Guides
+:page-nav_exclude: true
 :page-has_children: true
 :page-nav_order: 2
 
diff --git a/Documentation/index.adoc b/Documentation/index.adoc
index 3079847..ea28533 100644
--- a/Documentation/index.adoc
+++ b/Documentation/index.adoc
@@ -1,13 +1,32 @@
-= Spectrum Docs
+= Spectrum Documentation
 :page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-Spectrum is a compartmentalized operating system.
 
-If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting
-Spectrum].
+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.
+
+== Using Spectrum
 
 To learn about what Spectrum is and how it's implemented, start with
-the xref:architecture.adoc[architecture overview].
+the xref:about/architecture.adoc[architecture overview].
+
+If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run]
+ to setup a development environment.
+
+
+== Developing and Contributing
+
+Spectrum is made of free and open-source software.  It is free for anyone to
+ use, modify, and distribute.
+
+Once you are up and rinning, see
+ xref:../development/index.adoc[Development] to understand how to work with
+ patches, debug the system or build the documentation.
+
+If you are thinking of contributing to Spectrum docs, see
+ xref:../development/building-documentation.adoc[Building Documentation].
diff --git a/Documentation/b4.adoc b/Documentation/installation/b4.adoc
similarity index 93%
rename from Documentation/b4.adoc
rename to Documentation/installation/b4.adoc
index 489ced4..58efd0e 100644
--- a/Documentation/b4.adoc
+++ b/Documentation/installation/b4.adoc
@@ -1,5 +1,6 @@
 = Installing and Configuring b4
-:page-parent: Tutorials
+:page-parent: Build and Run
+:page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
@@ -19,7 +20,7 @@ of the Spectrum root's nix-shell.
 
 You should be able to install b4 from your package manager.
 
-Using Nix, you can start a shell with b4 available by running
+Using Nix, you can start a shell with b4 available by running:
 
 [listing]
 [source,shell]
diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc
similarity index 80%
rename from Documentation/binary-cache.adoc
rename to Documentation/installation/binary-cache.adoc
index 6e69b39..dff12e1 100644
--- a/Documentation/binary-cache.adoc
+++ b/Documentation/installation/binary-cache.adoc
@@ -1,5 +1,6 @@
-= Setting Up the Binary Cache
-:page-parent: How-to Guides
+= Setting Up Binary Cache
+:page-parent: Build and Run
+:page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -20,10 +21,9 @@ encounter any trouble with it.
 The binary cache is currently not able to provide logs, due to a
 https://github.com/NixOS/nix/pull/6051[Nix bug].
 
-== On NixOS
+== For NixOS
 
-The following configuration adds the Spectrum binary cache as a
-substituter, and tells Nix to trust builds signed with its public key.
+Add the following configuration to /etc/nixos/configuration.nix:
 
 [source,nix]
 ----
@@ -38,7 +38,13 @@ substituter, and tells Nix to trust builds signed with its public key.
 }
 ----
 
-== On Non-NixOS systems
+This configuration adds the Spectrum binary cache as a substituter and makes
+Nix to trust builds signed with its public key.
+
+To apply changes, rebuild your system with the https://nixos.wiki/wiki/Nixos-rebuild[nixos-rebuild] command.
+
+
+== For Non-NixOS Systems
 
 Add the following configuration to /etc/nix/nix.conf:
 
diff --git a/Documentation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc
similarity index 82%
rename from Documentation/getting-spectrum.adoc
rename to Documentation/installation/getting-spectrum.adoc
index b3fa1ef..c365a93 100644
--- a/Documentation/getting-spectrum.adoc
+++ b/Documentation/installation/getting-spectrum.adoc
@@ -1,5 +1,6 @@
 = Getting Spectrum
-:page-parent: Tutorials
+:page-parent: Build and Run
+:page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -34,7 +35,7 @@ nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run'
 This builds just enough of Spectrum to try it out in a VM, but it will
 still take a very long time.
 
-== Building an installer
+== Building Installer
 
 [source,shell]
 ----
@@ -47,8 +48,7 @@ This will take a very long time, but when it's done, a symbolic link
 named "result" will appear, pointing to a Spectrum USB installer
 image.
 
-CAUTION: Spectrum is not yet suitable for real-world use.  Do not use
-your Spectrum system for anything important or sensitive.  Spectrum is
-currently missing many important security properties, and there is no
-procedure for updating to new versions of Spectrum -- you have to
-reinstall.
+CAUTION: Do not use Spectrum for anything important or sensitive as it is not
+yet suitable for real-world use.  Many important security properties are
+currently missing, and there is no procedure for updating to
+new versions—you have to reinstall the OS.
diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
new file mode 100644
index 0000000..2c4e9c7
--- /dev/null
+++ b/Documentation/installation/index.adoc
@@ -0,0 +1,26 @@
+= Build and Run
+:description: How to download and install Spectrum OS.
+:page-nav_order: 2
+:page-has_children: true
+:page-has_toc: false
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+
+To start working with Spectrum, you need:
+
+* xref:../installation/binary-cache.adoc[Set up the binary cache] to speed up the build process.
+* xref:../installation/getting-spectrum.adoc[Build Spectrum] from the source.
+* xref:../installation/b4.adoc[Install and configure the b4 utility] to be able to work with patches.
+
+TIP: Currently, Spectrum works only on x86-64.  AAarch64 support is in
+development.  If you have the configuration layer, you can
+xref:../development/build-configuration.adoc[configure the build] to be able to
+work with specific devices.
+
+== Uninstalling and Updating
+
+Currently, there is no implementation for a software update.
+
+You can replace Spectrum by installing another OS.
diff --git a/Documentation/reference.adoc b/Documentation/reference.adoc
index 44b359d..55259ea 100644
--- a/Documentation/reference.adoc
+++ b/Documentation/reference.adoc
@@ -1,6 +1,5 @@
 = Reference
-:page-has_children: true
-:page-nav_order: 3
+:page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/tutorials.adoc b/Documentation/tutorials.adoc
index cd1fb12..fcef31b 100644
--- a/Documentation/tutorials.adoc
+++ b/Documentation/tutorials.adoc
@@ -1,6 +1,5 @@
 = Tutorials
-:page-nav_order: 1
-:page-has_children: true
+:page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/user-partition.adoc b/Documentation/user-partition.adoc
deleted file mode 100644
index 73bc0d0..0000000
--- a/Documentation/user-partition.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-= The User Partition
-:page-parent: Explanation
-
-// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
-// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
-
-The Spectrum host system is immutable, so configuration and user data
-lives on a separate partition.  The host system discovers the user
-partition by looking for the special partition type
-`9293e1ff-cee4-4658-88be-898ec863944f`.  This behavior can be
-overridden with the `ext` parameter on the host's kernel command line,
-which works in a similar way to the standard Linux `root` parameter.
-- 
2.34.1



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-10-28 11:05 ` [PATCH] Docs: new structure Jenni Nikolaenko
@ 2022-10-28 11:24   ` Jenni Nikolaenko
  2022-11-01 12:14     ` Alyssa Ross
  2022-11-01 12:13   ` Alyssa Ross
  1 sibling, 1 reply; 12+ messages in thread
From: Jenni Nikolaenko @ 2022-10-28 11:24 UTC (permalink / raw)
  To: devel

I created another big mess with me second version of the same patch :D
Please do not throw anything heavy))

Also, I left comments here: https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/thread/ERGLBDIVIXBLFNNKTWTBRUDFUXWLBOF7/


^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-10-28 11:05 ` [PATCH] Docs: new structure Jenni Nikolaenko
  2022-10-28 11:24   ` Jenni Nikolaenko
@ 2022-11-01 12:13   ` Alyssa Ross
  2022-11-04 13:57     ` Jenni Nikolaenko
  1 sibling, 1 reply; 12+ messages in thread
From: Alyssa Ross @ 2022-11-01 12:13 UTC (permalink / raw)
  To: Jenni Nikolaenko; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 16688 bytes --]

Hi Jenni, thank you for the new patch!  I really like where this is
going, and the comments I have this time should almost all be small
things that are easy to fix.

BTW: when you submit the next version of your patch, please add a -v3
argument to your git send-email command to mark it as version 3, to make
it easier for people following the progress of the patch (like me!) to
keep the different versions straight.  More info here:
https://spectrum-os.org/doc/first-patch.html#feedback

On Fri, Oct 28, 2022 at 02:05:58PM +0300, Jenni Nikolaenko wrote:
> Create separate folders for new parent pages, update Introduction page,
> remove a and the articles from titles, quick check text for simple english
>
> Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
> ---
>
> diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc
> similarity index 84%
> rename from Documentation/architecture.adoc
> rename to Documentation/about/architecture.adoc
> index 1c4307b..c1af320 100644
> --- a/Documentation/architecture.adoc
> +++ b/Documentation/about/architecture.adoc
> @@ -35,7 +33,7 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual
>  Machine] (KVM) to provide lightweight, hardware-accelerated VMs.
>
>  While Linux (including KVM) is portable between many hardware architectures,
> -cloud-hypervisor supports only x86_64 and aarch64.  Spectrum currently only
> +cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only

This is one of a few sentences that the patch still changes to be
single-spaced.

>  works on x86_64, but aarch64 support is in development.
>
>  https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service

> diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc
> new file mode 100644
> index 0000000..9e2a47e
> --- /dev/null
> +++ b/Documentation/about/index.adoc
> @@ -0,0 +1,30 @@
> += About Spectrum
> +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.

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):

https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description

> +:page-nav_order: 1
> +:page-has_children: true
> +
> +// SPDX-FileCopyrightText: 2022 Unikie
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +Spectrum is a Linux-based system that uses Nix package manager and Nixpkgs
> +collection of packages.

*The* Nix package manager, and *the* Nixpkgs package collection.

Maybe we could link to them too?

> +
> +This gives an actively-developed base with good
> +hardware support, powerful and optimised compartmentalization primitives in
> +KVM, and the reproducible packaging and configuration system that is important
> +for a maintainable compartmentalized system.
> +
> +== Why Spectrum
> +
> +* User data and applications are managed centrally while remaining isolated.
> +That means that the system can be backed up and managed as a whole, rather than
> +mixed up in several dozen VMs.
> +
> +* The host system and isolated environments are managed declaratively and
> +reproducibly using the Nix package manager.
> +This can save the user the burden of maintaining many different virtual
> +computers, allowing finer-grained resource access controls and making it
> +possible to verify the software running across all environments.
> +
> +TIP: If you are interested in why we do something _this_ way instead of _that_
> +way, see xref:../decisions/index.adoc[Architecture Decision Records].

This whole page is excellent, thanks a lot!

> diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
> new file mode 100644
> index 0000000..1fe4d8b
> --- /dev/null
> +++ b/Documentation/development/index.adoc
> @@ -0,0 +1,31 @@
> += Development
> +:description: Development progress, general development practices
> +:page-nav_order: 4
> +:page-has_children: true
> +
> +// SPDX-FileCopyrightText: 2022 Unikie
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +Spectrum is free software, currently under active development.
> +
> +If you made changes in a source code,
> +https://spectrum-os.org/installation/getting-spectrum.html#building-an-installer[rebuild Spectrum],
> +xref:../development/testing-patches.adoc[test your patch] and

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.

> +then https://spectrum-os.org/development/first-patch.html#submitting-changes[submit your changes for review].
> +
> +== Developer Setup
> +
> +Before starting, make sure you are familiar with
> +https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] and the

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.

> +https://nixos.org/manual/nix/stable/introduction.html[Nix package manager].
> +
> +== Mailing Lists
> +
> +The Spectrum project runs several
> +https://spectrum-os.org/mailman3/lists/?all-lists[mailing lists] on which you
> +can ask your questions or help other people with the questions they have.  All
> +the Spectrum developers as well as many long time Linux and Spectrum users are
> +on the lists.
> +
> +For real-time feedback, use
> +https://spectrum-os.org/participating.html#irc[IRC/Matrix channel].

> diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc
> similarity index 81%
> rename from Documentation/testing-patches.adoc
> rename to Documentation/development/testing-patches.adoc
> index 743cd6e..600cf0f 100644
> --- a/Documentation/testing-patches.adoc
> +++ b/Documentation/development/testing-patches.adoc
> @@ -1,5 +1,7 @@
>  = Testing Patches
> -:page-parent: How-to Guides
> +:page-parent: Working with Patches
> +:page-grand_parent: Development
> +:page-nav_order: 2
>
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-FileCopyrightText: 2022 Unikie
> @@ -9,7 +11,7 @@ Potential changes to Spectrum are posted to and discussed on the
>  https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org]
>  mailing list.
>
> -== Apply the patch
> +== Apply Patch
>
>  . Find the patch series you want to test on
>    https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox].
> @@ -28,35 +30,31 @@ of the Spectrum root's nix-shell, which allows you to skip this step.
>    with the patch's Message-Id to download all the patches in the
>    series into a file.
>  +
> -[example]

My comments from the previous version still apply here — this [example]
attribute shouldn't be removed, …

>  [source,shell]
>  ----
>  b4 am 20220511092352.70E54C980@atuin.qyliss.net
>  ----
> -
> -. b4 will indicate the file name it has downloaded the patches into
> -  with a line like:
> +b4 will indicate the file name it has downloaded the patches into with a line
> +like:
>  +
> -[example]
> -[listing]
> +[source,shell]

… and this was also correct before.

> +----
>  Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
> +----
> +. Run `git am` on that file to apply the patches. For example:
>  +
> -Run `git am` on that file to apply the patches, for example:
> -+
> -[example]
>  [source,shell]
>  ----
>  git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
>  ----
>
> -== Post your test results
> +== Post Your Results
>
> -When you've tested a patch, it's really helpful to
> +When you tested a patch, it is helpful to
>  xref:replying.adoc[reply] with your test results.
>
> -If the patch worked for you, please reply to it and include a line
> -like the following, separated from any reply text:
> -
> +If the patch worked for you, please reply to it and include a line like the following, separated from any reply text:
> +[source,shell]

This isn't shell source code, so we shouldn't use this attribute here.

>  ----
>  Tested-by: John Smith <john@example.com>
>  ----
> @@ -66,10 +64,10 @@ patch replies will be automatically included in the commit message
>  when a patch is applied.
>
>  It's also helpful to explain in your reply how you tested the patch,
> -but you don't have to if it's obvious.  (For example, if a patch is
> +but you don't have to if it's obvious.  For example, if a patch is
>  supposed to fix a bug, and you verified that after applying the patch
>  the bug is fixed, just the Tested-by line on its own is enough to
> -indicate that.)
> +indicate that.
>
>  If you found an issue with the patch, do not include a Tested-by line,
>  and instead reply to the patch explaining what you tested, what you

> diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc
> index b39cc6d..f682129 100644
> --- a/Documentation/explanation.adoc
> +++ b/Documentation/explanation.adoc
> @@ -1,6 +1,5 @@
>  = Explanation
> -:page-has_children: true
> -:page-nav_order: 4
> +:page-nav_exclude: true

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?

>
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

> diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc
> new file mode 100644
> index 0000000..639e0a6
> --- /dev/null
> +++ b/Documentation/getting-started/index.adoc
> @@ -0,0 +1,14 @@
> += Getting Started
> +:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). Ready to get started with Spectrum OS? After installing you can create VMs and then configure each one.

Spectrum, not Spectrum OS. :)

> +:page-nav_order: 3
> +:page-has_children: true
> +:page-has_toc: false
> +
> +// SPDX-FileCopyrightText: 2022 Unikie
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +Ready to get started with Spectrum? Here is what you can do next:
> +
> +* xref:../getting-started/creating-vms.adoc[Create your own VM] to use others applications.
> +* xref:../getting-started/running-vms.adoc[Start some applications].
> +* If needed, xref:../getting-started/user-partition.adoc[change the user partition type].

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.

> diff --git a/Documentation/index.adoc b/Documentation/index.adoc
> index 3079847..ea28533 100644
> --- a/Documentation/index.adoc
> +++ b/Documentation/index.adoc
> @@ -1,13 +1,32 @@
> -= Spectrum Docs
> += Spectrum Documentation
>  :page-nav_exclude: true
>
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
> +// SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>
> -Spectrum is a compartmentalized operating system.
>
> -If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting
> -Spectrum].
> +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.
> +
> +== Using Spectrum
>
>  To learn about what Spectrum is and how it's implemented, start with
> -the xref:architecture.adoc[architecture overview].
> +the xref:about/architecture.adoc[architecture overview].
> +
> +If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run]
> + to setup a development environment.
> +
> +
> +== Developing and Contributing
> +
> +Spectrum is made of free and open-source software.  It is free for anyone to
> + use, modify, and distribute.
> +
> +Once you are up and rinning, see

typo: rinning

> + xref:../development/index.adoc[Development] to understand how to work with
> + patches, debug the system or build the documentation.

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.

> +
> +If you are thinking of contributing to Spectrum docs, see
> + xref:../development/building-documentation.adoc[Building Documentation].

> diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc
> similarity index 80%
> rename from Documentation/binary-cache.adoc
> rename to Documentation/installation/binary-cache.adoc
> index 6e69b39..dff12e1 100644
> --- a/Documentation/binary-cache.adoc
> +++ b/Documentation/installation/binary-cache.adoc
> @@ -1,5 +1,6 @@
> -= Setting Up the Binary Cache
> -:page-parent: How-to Guides
> += Setting Up Binary Cache
> +:page-parent: Build and Run
> +:page-nav_order: 1
>
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> @@ -20,10 +21,9 @@ encounter any trouble with it.
>  The binary cache is currently not able to provide logs, due to a
>  https://github.com/NixOS/nix/pull/6051[Nix bug].
>
> -== On NixOS
> +== For NixOS
>
> -The following configuration adds the Spectrum binary cache as a
> -substituter, and tells Nix to trust builds signed with its public key.
> +Add the following configuration to /etc/nixos/configuration.nix:
>
>  [source,nix]
>  ----
> @@ -38,7 +38,13 @@ substituter, and tells Nix to trust builds signed with its public key.
>  }
>  ----
>
> -== On Non-NixOS systems
> +This configuration adds the Spectrum binary cache as a substituter and makes
> +Nix to trust builds signed with its public key.

"makes Nix to trust" is ungrammatical.  This should be
"tells Nix to trust" or "makes Nix trust".

> +
> +To apply changes, rebuild your system with the https://nixos.wiki/wiki/Nixos-rebuild[nixos-rebuild] command.
> +
> +
> +== For Non-NixOS Systems
>
>  Add the following configuration to /etc/nix/nix.conf:
>
> diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
> new file mode 100644
> index 0000000..2c4e9c7
> --- /dev/null
> +++ b/Documentation/installation/index.adoc
> @@ -0,0 +1,26 @@
> += Build and Run
> +:description: How to download and install Spectrum OS.
> +:page-nav_order: 2
> +:page-has_children: true
> +:page-has_toc: false
> +
> +// SPDX-FileCopyrightText: 2022 Unikie
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +
> +To start working with Spectrum, you need:
> +
> +* xref:../installation/binary-cache.adoc[Set up the binary cache] to speed up the build process.
> +* xref:../installation/getting-spectrum.adoc[Build Spectrum] from the source.
> +* xref:../installation/b4.adoc[Install and configure the b4 utility] to be able to work with patches.

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.

> +
> +TIP: Currently, Spectrum works only on x86-64.  AAarch64 support is in
> +development.  If you have the configuration layer, you can
> +xref:../development/build-configuration.adoc[configure the build] to be able to
> +work with specific devices.

One too many "a"s here — it's "aarch64".

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

> +
> +== Uninstalling and Updating
> +
> +Currently, there is no implementation for a software update.
> +
> +You can replace Spectrum by installing another OS.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-10-28 11:24   ` Jenni Nikolaenko
@ 2022-11-01 12:14     ` Alyssa Ross
  0 siblings, 0 replies; 12+ messages in thread
From: Alyssa Ross @ 2022-11-01 12:14 UTC (permalink / raw)
  To: Jenni Nikolaenko; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 351 bytes --]

On Fri, Oct 28, 2022 at 11:24:59AM -0000, Jenni Nikolaenko wrote:
> I created another big mess with me second version of the same patch :D
> Please do not throw anything heavy))
>
> Also, I left comments here: https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/thread/ERGLBDIVIXBLFNNKTWTBRUDFUXWLBOF7/

No mess!  You did it right! :)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-11-01 12:13   ` Alyssa Ross
@ 2022-11-04 13:57     ` Jenni Nikolaenko
  2022-11-08  9:03       ` Alyssa Ross
  0 siblings, 1 reply; 12+ messages in thread
From: Jenni Nikolaenko @ 2022-11-04 13:57 UTC (permalink / raw)
  To: devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-11-04 13:57     ` Jenni Nikolaenko
@ 2022-11-08  9:03       ` Alyssa Ross
  2022-11-08 15:05         ` Jenni Nikolaenko
  0 siblings, 1 reply; 12+ messages in thread
From: Alyssa Ross @ 2022-11-08  9:03 UTC (permalink / raw)
  To: Jenni Nikolaenko; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 601 bytes --]

On Fri, Nov 04, 2022 at 01:57:22PM -0000, Jenni Nikolaenko wrote:
> > > 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.

Ah, sorry, I was unclear about what I meant here.  I didn't mean that
the whole page was something that an end user wouldn't want to do, just
the last item on the list (changing the user partition type).  I think
this should still be the Getting Started page, it just shouldn't include
that last item.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-11-08  9:03       ` Alyssa Ross
@ 2022-11-08 15:05         ` Jenni Nikolaenko
  0 siblings, 0 replies; 12+ messages in thread
From: Jenni Nikolaenko @ 2022-11-08 15:05 UTC (permalink / raw)
  To: devel

> > Ah, sorry, I was unclear about what I meant here.  I didn't mean that
> the whole page was something that an end user wouldn't want to do, just
> the last item on the list (changing the user partition type).  I think
> this should still be the Getting Started page, it just shouldn't include
> that last item.
Fixed.
Returned the Getting Started section back and added the Appendices section.
Now we have:
- Getting Started
-- Creating VMs
-- Running VMs
- Appendices
-- Appendix A. User Partition
-- Appendix B. UUID



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-09-19  9:30 ` Alyssa Ross
  2022-09-28 12:52   ` Jenni N
@ 2022-10-28 11:22   ` Jenni Nikolaenko
  1 sibling, 0 replies; 12+ messages in thread
From: Jenni Nikolaenko @ 2022-10-28 11:22 UTC (permalink / raw)
  To: devel

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


^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-09-28 12:52   ` Jenni N
@ 2022-09-29  8:58     ` Alyssa Ross
  0 siblings, 0 replies; 12+ messages in thread
From: Alyssa Ross @ 2022-09-29  8:58 UTC (permalink / raw)
  To: Jenni N; +Cc: devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-09-19  9:30 ` Alyssa Ross
@ 2022-09-28 12:52   ` Jenni N
  2022-09-29  8:58     ` Alyssa Ross
  2022-10-28 11:22   ` Jenni Nikolaenko
  1 sibling, 1 reply; 12+ messages in thread
From: Jenni N @ 2022-09-28 12:52 UTC (permalink / raw)
  To: devel

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


^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Docs: new structure
  2022-09-06 13:55 Jenni Nikolaenko
@ 2022-09-19  9:30 ` Alyssa Ross
  2022-09-28 12:52   ` Jenni N
  2022-10-28 11:22   ` Jenni Nikolaenko
  0 siblings, 2 replies; 12+ messages in thread
From: Alyssa Ross @ 2022-09-19  9:30 UTC (permalink / raw)
  To: Jenni Nikolaenko; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 42877 bytes --]

Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com> writes:

> Create separate folders for new parent pages, update Introduction page,
> remove a and the articles from titles, quick check text for simple english
>
> Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
> ---

Hi Jenni, thank you for the patch!

I really love the simple language in the new documentation you've
written.  I think it'll be a big help to people coming to the project.

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.

In future, could you please separate changes like this into a single
patch/commit per change?  For example, one commit to move the files
around, another for the navigation structure changes, and another for
the language changes?  It makes it much easier to review as it makes it
possible to look at each logical change one at a time, it will help to
avoid merge conflicts, and it means that some changes can be committed
while others are still in discussion, so progress is faster.

I've left more feedback inline below.  This is a big patch, so there's a
lot of feedback — I hope it's not too intimidating.  With more commits,
where each one was smaller, the reviews would also be a bit more
manageable in size!

>  Documentation/{ => about}/architecture.adoc   | 19 ++++-----
>  Documentation/about/index.adoc                | 21 ++++++++++
>  .../decisions/001-host-update-mechanism.adoc  |  2 +-
>  .../decisions/002-install-options.adoc        |  4 +-
>  Documentation/decisions/003-partitioning.adoc |  2 +-
>  .../004-data-at-rest-encryption.adoc          |  2 +-
>  .../005-virtual-machine-monitor.adoc          |  2 +-
>  .../decisions/006-drivers-on-host.adoc        |  2 +-
>  .../decisions/007-usb-virtual-machines.adoc   |  2 +-
>  ...008-inter-vm-communication-mechanisms.adoc |  2 +-
>  Documentation/decisions/index.adoc            |  2 +-
>  .../building-documentation.adoc               | 10 ++---
>  .../{ => development}/debugging.adoc          |  7 ++--
>  .../{ => development}/first-patch.adoc        | 28 +++++++------
>  Documentation/development/index.adoc          | 17 ++++++++
>  Documentation/{ => development}/replying.adoc |  4 +-
>  .../{ => development}/reviewing-patches.adoc  |  4 +-
>  .../{ => development}/testing-patches.adoc    | 42 ++++++++-----------
>  .../{ => development}/uuid-reference.adoc     |  4 +-
>  Documentation/explanation.adoc                |  3 +-
>  .../{ => getting-started}/creating-vms.adoc   |  2 +-
>  Documentation/getting-started/index.adoc      |  7 ++++
>  .../{ => getting-started}/running-vms.adoc    |  2 +-
>  .../{ => getting-started}/user-partition.adoc |  8 ++--
>  Documentation/how-to.adoc                     |  1 +
>  Documentation/index.adoc                      | 22 +++++++---
>  Documentation/{ => installation}/b4.adoc      |  3 +-
>  .../{ => installation}/binary-cache.adoc      | 11 ++---
>  .../{ => installation}/getting-spectrum.adoc  | 11 ++---
>  Documentation/installation/index.adoc         | 18 ++++++++
>  Documentation/reference.adoc                  |  3 +-
>  Documentation/tutorials.adoc                  |  3 +-
>  32 files changed, 171 insertions(+), 99 deletions(-)
>  rename Documentation/{ => about}/architecture.adoc (84%)
>  create mode 100644 Documentation/about/index.adoc
>  rename Documentation/{ => development}/building-documentation.adoc (85%)
>  rename Documentation/{ => development}/debugging.adoc (92%)
>  rename Documentation/{ => development}/first-patch.adoc (83%)
>  create mode 100644 Documentation/development/index.adoc
>  rename Documentation/{ => development}/replying.adoc (93%)
>  rename Documentation/{ => development}/reviewing-patches.adoc (89%)
>  rename Documentation/{ => development}/testing-patches.adoc (62%)
>  rename Documentation/{ => development}/uuid-reference.adoc (98%)
>  rename Documentation/{ => getting-started}/creating-vms.adoc (98%)
>  create mode 100644 Documentation/getting-started/index.adoc
>  rename Documentation/{ => getting-started}/running-vms.adoc (93%)
>  rename Documentation/{ => getting-started}/user-partition.adoc (80%)
>  rename Documentation/{ => installation}/b4.adoc (96%)
>  rename Documentation/{ => installation}/binary-cache.adoc (90%)
>  rename Documentation/{ => installation}/getting-spectrum.adoc (85%)
>  create mode 100644 Documentation/installation/index.adoc

Thank you for organising the AsciiDoc files into subdirectories.  The
main Documentation directory was definitely getting a bit unwieldy.

> diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc
> similarity index 84%
> rename from Documentation/architecture.adoc
> rename to Documentation/about/architecture.adoc
> index 1c4307b..db82d60 100644
> --- a/Documentation/architecture.adoc
> +++ b/Documentation/about/architecture.adoc
> @@ -1,17 +1,16 @@
>  = Architecture
> -:page-parent: Explanation
> +:page-parent: About Spectrum OS

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

>  
>  // SPDX-FileCopyrightText: 2022 Unikie
> +// SPDX-FileCopyrightText: 2022 Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>

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

>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>  
> -== Introduction
> +Spectrum OS is based on the principle of security by compartmentalization.
>  
> -Spectrum is based on the principle of security by
> -compartmentalization.  The high level stack is illustrated in the
> -following diagram:
> +The high level stack is illustrated in the following diagram:
>  
> -image::diagrams/stack.svg[]
> +image::../diagrams/stack.svg[]
>  
>  The default set of virtual machines includes two application VMs,
>  _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web
> @@ -26,7 +25,7 @@ https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant
>  decisions] are xref:decisions/index.adoc[recorded] as lightweight
>  https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs].
>  
> -== The Spectrum host system
> +== Spectrum Host System
>  
>  Compartmentalization is implemented using
>  https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines.
> @@ -35,7 +34,7 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual
>  Machine] (KVM) to provide lightweight, hardware-accelerated VMs.
>  
>  While Linux (including KVM) is portable between many hardware architectures,
> -cloud-hypervisor supports only x86_64 and aarch64.  Spectrum currently only
> +cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only

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?

>  works on x86_64, but aarch64 support is in development.
>  
>  https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service
> @@ -44,7 +43,7 @@ and service scripts.
>  
>  https://wayland.freedesktop.org/[Wayland] is used for window management and
>  display.  The Wayland architecture is well documented
> -https://wayland.freedesktop.org/architecture.html[here].  The host provides only
> +https://wayland.freedesktop.org/architecture.html[here]. The host provides only
>  a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used
>  for interacting with VM consoles.  In future it will be possible for application
>  VMs to display windows on the single Wayland compositor on the host system,
> @@ -57,7 +56,7 @@ https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion
>  and security hardening on memory allocation].  Kernel hardening will be
>  investigated in future.
>  
> -== Exploring the Spectrum dependency tree
> +== Spectrum Dependency Tree
>  
>  For a detailed, interactive view of dependencies, use
>  https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository:
> diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc
> new file mode 100644
> index 0000000..a882852
> --- /dev/null
> +++ b/Documentation/about/index.adoc
> @@ -0,0 +1,21 @@
> += About Spectrum OS
> +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.

I haven't seen this description field before.  Where's it used?

> +:page-nav_order: 1
> +:page-has_children: true
> +
> +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +Spectrum is a Linux-based system, derived from NixOS. This gives an actively-developed base with good hardware support, powerful and optimised compartmentalization primitives in KVM, and the reproducible packaging and configuration system that is important for a maintainable compartmentalized system.

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.

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

> +
> +== Why Spectrum
> +
> +There are several features that make Spectrum OS unique:
> +
> +* User data and applications are managed centrally, while remaining isolated.
> +That means that the system can be backed up and managed as a whole, rather than mixed up in several dozen VMs.

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?

> +
> +* The host system and isolated environments are managed declaratively and reproducibly using the Nix package manager.
> +This can save the user the burden of maintaining many different virtual computers, allowing finer-grained resource access controls and making it possible to verify the software running across all environments.
> +
> +TIP: If you are interested in why we do something _this_ way instead of _that_ way, see xref:../decisions/index.adoc[Architecture Decision Records].

Nice tip.  That's a great way to describe it.

> diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc
> index 574deb4..7032146 100644
> --- a/Documentation/decisions/001-host-update-mechanism.adoc
> +++ b/Documentation/decisions/001-host-update-mechanism.adoc
> @@ -1,6 +1,6 @@
>  = 001 Host Update Mechanism
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc
> index 4412b53..a7c4175 100644
> --- a/Documentation/decisions/002-install-options.adoc
> +++ b/Documentation/decisions/002-install-options.adoc
> @@ -1,6 +1,6 @@
> -= 002 Install options
> += 002 Install Options
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc
> index 8494ea4..b00f528 100644
> --- a/Documentation/decisions/003-partitioning.adoc
> +++ b/Documentation/decisions/003-partitioning.adoc
> @@ -1,6 +1,6 @@
>  = 003 Partitioning
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc
> index 26fe273..27323db 100644
> --- a/Documentation/decisions/004-data-at-rest-encryption.adoc
> +++ b/Documentation/decisions/004-data-at-rest-encryption.adoc
> @@ -1,6 +1,6 @@
>  = 004 Data at Rest Encryption
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/005-virtual-machine-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc
> index db81c72..df5a65e 100644
> --- a/Documentation/decisions/005-virtual-machine-monitor.adoc
> +++ b/Documentation/decisions/005-virtual-machine-monitor.adoc
> @@ -1,6 +1,6 @@
>  = 005 Virtual Machine Monitor
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc
> index 872044e..86d3105 100644
> --- a/Documentation/decisions/006-drivers-on-host.adoc
> +++ b/Documentation/decisions/006-drivers-on-host.adoc
> @@ -1,6 +1,6 @@
>  = 006 Drivers on Host
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc
> index 3bdf78b..24dac65 100644
> --- a/Documentation/decisions/007-usb-virtual-machines.adoc
> +++ b/Documentation/decisions/007-usb-virtual-machines.adoc
> @@ -1,6 +1,6 @@
>  = 007 USB Virtual Machine
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
> index a1b7d49..9fce4ef 100644
> --- a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
> +++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
> @@ -1,6 +1,6 @@
>  = 008 Inter-VM Communication Mechanisms
>  :page-parent: Architecture Decision Records
> -:page-grand_parent: Explanation
> +:page-grand_parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc
> index 772f382..4f3a7e1 100644
> --- a/Documentation/decisions/index.adoc
> +++ b/Documentation/decisions/index.adoc
> @@ -1,6 +1,6 @@
>  = Architecture Decision Records
>  :page-has_children: true
> -:page-parent: Explanation
> +:page-parent: About Spectrum OS
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/building-documentation.adoc b/Documentation/development/building-documentation.adoc
> similarity index 85%
> rename from Documentation/building-documentation.adoc
> rename to Documentation/development/building-documentation.adoc
> index b491105..da5fa8c 100644
> --- a/Documentation/building-documentation.adoc
> +++ b/Documentation/development/building-documentation.adoc
> @@ -1,5 +1,5 @@
> -= Building the Documentation
> -:page-parent: Tutorials
> += Building Documentation
> +:page-parent: Development
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> @@ -47,6 +47,6 @@ IMPORTANT: Jekyll doesn't handle rendering of the draw.io diagrams, so
>  if you modify any of those, or add new ones, you'll have to run
>  `scripts/build.sh` again to do a full rebuild of the site.
>  
> -Once you've made your changes to the documentation, see
> -xref:first-patch.adoc[Sending Your First Patch] for information
> -about how to submit them for review.
> +Once you made your changes to the documentation, see
> +xref:first-patch.adoc[Patching] for information
> +on how to submit your patch for review.
> diff --git a/Documentation/debugging.adoc b/Documentation/development/debugging.adoc
> similarity index 92%
> rename from Documentation/debugging.adoc
> rename to Documentation/development/debugging.adoc
> index 3871a7c..6e529a9 100644
> --- a/Documentation/debugging.adoc
> +++ b/Documentation/development/debugging.adoc
> @@ -1,7 +1,6 @@
> -= Debugging Spectrum
> -:page-parent: Explanation
> -:toc:
> -:toclevels: 1
> += Debugging
> +:page-parent: Development
> +:page-nav_order: 2
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/first-patch.adoc b/Documentation/development/first-patch.adoc
> similarity index 83%
> rename from Documentation/first-patch.adoc
> rename to Documentation/development/first-patch.adoc
> index 30672b9..7b8dd1d 100644
> --- a/Documentation/first-patch.adoc
> +++ b/Documentation/development/first-patch.adoc
> @@ -1,11 +1,12 @@
> -= Sending Your First Patch
> -:page-parent: Tutorials
> += Patching
> +:page-parent: Development
> +:page-nav_order: 1
> +:page-has_children: true
> +:toc: preamble
>  
>  // SPDX-FileCopyrightText: 2022 Unikie
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>  
> -== Prerequisites
> -
>  This tutorial assumes that you already have basic
>  https://git-scm.com/[git] experience.
>  
> @@ -14,10 +15,10 @@ https://spectrum-os.org/git/[Spectrum source tree].  You'll also need
>  to have configured `git send-email` — a guide for this can be found at
>  https://git-send-email.io/.
>  
> -== Making your changes
> +== Making Changes
>  
> -If you've worked on any git repository before, the process for making
> -your changes will probably be very familiar.
> +If you worked on any git repository before, the process for making
> +your changes will be very familiar.

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"?

>  
>  1. Create a branch for your changes:
>  +
> @@ -39,7 +40,7 @@ indicates your acceptance of the
>  https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's
>  Certificate of Origin], which is mandatory for Spectrum patches.
>  
> -== Submitting changes
> +== Submitting Changes
>  
>  Once you're happy with how the commits on your branch look, run:
>  
> @@ -64,13 +65,14 @@ message that will be sent before all of your patches.
>  
>  Once your patch has been submitted, wait for it to be reviewed.
>  Feedback, if any, will be sent as email replies to your submitted
> -patch.  You can respond to feedback in your mail client.  Please use
> -the Reply All button to ensure that your messages are sent to the
> +patch.  You can respond to feedback in your mail client.
> +
> +Use the *Reply All* button to sent your messages to the
>  mailing list as well as to the person who sent the feedback.
>  
> -If you need to make changes to your patch, and submit a new version,
> +If you need to make changes to your patch and submit a new version,
>  use https://git-rebase.io/[`git rebase`] to create a new version of
> -your patch(es), and submit it like this:
> +your patch(es) and then submit it like this:

Good catch with the commas, thanks.

>  
>  [source,shell]
>  ----
> @@ -81,7 +83,7 @@ The added `-v2` flag indicates that this is version two of your
>  patch set.  If your patches require more rounds of changes, submit
>  subsequent rounds with `-v3`, `-v4`, etc. as appropriate.
>  
> -If you'd like to describe what has changed from the previous version
> +If you would like to describe what has changed from the previous version
>  of your patches, you can do so in a xref:cover-letter[cover letter]
>  as described above.
>  
> diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
> new file mode 100644
> index 0000000..471daf7
> --- /dev/null
> +++ b/Documentation/development/index.adoc
> @@ -0,0 +1,17 @@
> += Development
> +:description: Development progress, general development practices
> +:page-nav_order: 4
> +:page-has_children: true
> +
> +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +Spectrum is free software, currently under active development.
> +
> +== Developer Setup
> +
> +Before starting, make sure you are familiar with https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] and the https://nixos.org/manual/nix/stable/introduction.html[Nix package manager].
> +
> +== Mailing Lists
> +
> +The Spectrum project runs several https://spectrum-os.org/mailman3/lists/?all-lists[mailing lists] on which you can ask your questions or help other people with the questions they have. All the Spectrum developers as well as many long time Linux and Spectrum users are on the lists.

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.

> diff --git a/Documentation/replying.adoc b/Documentation/development/replying.adoc
> similarity index 93%
> rename from Documentation/replying.adoc
> rename to Documentation/development/replying.adoc
> index bb8e31a..05740a0 100644
> --- a/Documentation/replying.adoc
> +++ b/Documentation/development/replying.adoc
> @@ -1,5 +1,7 @@
>  = Replying to Messages in the Mailing List Archives
> -:page-parent: Tutorials
> +:page-parent: Patching
> +:page-grand_parent: Development
> +:page-nav_order: 3
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc
> similarity index 89%
> rename from Documentation/reviewing-patches.adoc
> rename to Documentation/development/reviewing-patches.adoc
> index 63ff24e..c8c971f 100644
> --- a/Documentation/reviewing-patches.adoc
> +++ b/Documentation/development/reviewing-patches.adoc
> @@ -1,5 +1,7 @@
>  = Reviewing Patches
> -:page-parent: How-to Guides
> +:page-parent: Patching
> +:page-grand_parent: Development
> +:page-nav_order: 2
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc
> similarity index 62%
> rename from Documentation/testing-patches.adoc
> rename to Documentation/development/testing-patches.adoc
> index 8ba7804..99adfd2 100644
> --- a/Documentation/testing-patches.adoc
> +++ b/Documentation/development/testing-patches.adoc
> @@ -1,5 +1,8 @@
>  = Testing Patches
> -:page-parent: How-to Guides
> +:page-parent: Patching
> +:page-grand_parent: Development
> +:page-nav_order: 1
> +:toc: preamble
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> @@ -8,52 +11,41 @@ Potential changes to Spectrum are posted to and discussed on the
>  https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org]
>  mailing list.
>  
> -== Apply the patch
> +== Apply Patch
>  
>  If you haven't already, you'll first need to xref:b4.adoc[install and
>  configure] https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4].
>  Then:
>  
> -. Find the patch series you want to test on
> -  https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox].
> -. Navigate to the "permalink" page for any patch in the series.
> -. Copy the Message-Id for the patch, as shown on the permalink page, e.g.
> -  \20220511092352.70E54C980@atuin.qyliss.net.
> -. In a checkout of the appropriate git repository
> -  (https://spectrum-os.org/git/spectrum[Spectrum] or
> -  https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), Run `b4 am`
> -  with the patch's Message-Id to download all the patches in the
> -  series into a file.
> +1. Find the patch series you want to test on https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox].
> +2. Navigate to the "permalink" page for any patch in the series.
> +3. Copy the Message-Id for the patch, as shown on the permalink page, e.g.  \20220511092352.70E54C980@atuin.qyliss.net.
> +4. In a checkout of the appropriate git repository   (https://spectrum-os.org/git/spectrum[Spectrum] or   https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), run `b4 am` with the patch's Message-Id to download all the patches in the series into a file.

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?

>  +
> -[example]

The example attribute (when used without a title) doesn't currently make
any difference in output/styling, but I think it's useful to use anyway
in case we want to e.g. label examples in future.

>  [source,shell]
>  ----
>  b4 am 20220511092352.70E54C980@atuin.qyliss.net
>  ----
> -
> -. b4 will indicate the file name it has downloaded the patches into
> -  with a line like:
> +b4 will indicate the file name it has downloaded the patches into with a line like:
>  +
> -[example]
> -[listing]
> +[source,shell]
> +----
>  Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
> +----

This is just sample text output from git, not shell source code.

> +5. Run `git am` on that file to apply the patches, for example:
>  +
> -Run `git am` on that file to apply the patches, for example:
> -+
> -[example]
>  [source,shell]
>  ----
>  git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
>  ----
>  
> -== Post your test results
> +== Post Your Results
>  
>  When you've tested a patch, it's really helpful to
>  xref:replying.adoc[reply] with your test results.
>  
> -If the patch worked for you, please reply to it and include a line
> -like the following, separated from any reply text:
> -
> +If the patch worked for you, please reply to it and include a line like the following, separated from any reply text:
> +[source,shell]
>  ----
>  Tested-by: John Smith <john@example.com>
>  ----
> diff --git a/Documentation/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc
> similarity index 98%
> rename from Documentation/uuid-reference.adoc
> rename to Documentation/development/uuid-reference.adoc
> index 4b0b481..0eccc82 100644
> --- a/Documentation/uuid-reference.adoc
> +++ b/Documentation/development/uuid-reference.adoc
> @@ -1,5 +1,5 @@
>  = UUID Reference
> -:page-parent: Reference
> +:page-parent: Development
>  :toc: preamble
>  :toclevels: 1
>  
> @@ -40,7 +40,7 @@ xref:user-partition.adoc[Spectrum user partition].
>  
>  === `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e`
>  
> -https://github.com/endlessm/eos-installer["eosimages"] partition on the 
> +https://github.com/endlessm/eos-installer["eosimages"] partition on the
>  Spectrum combined live system / installer image.
>  
>  == Combined Image Partition IDs
> diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc
> index b39cc6d..f682129 100644
> --- a/Documentation/explanation.adoc
> +++ b/Documentation/explanation.adoc
> @@ -1,6 +1,5 @@
>  = Explanation
> -:page-has_children: true
> -:page-nav_order: 4
> +:page-nav_exclude: true
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc
> similarity index 98%
> rename from Documentation/creating-vms.adoc
> rename to Documentation/getting-started/creating-vms.adoc
> index d967098..e06be85 100644
> --- a/Documentation/creating-vms.adoc
> +++ b/Documentation/getting-started/creating-vms.adoc
> @@ -1,5 +1,5 @@
>  = Creating VMs
> -:page-parent: Reference
> +:page-parent: Getting Started
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc
> new file mode 100644
> index 0000000..1b468ab
> --- /dev/null
> +++ b/Documentation/getting-started/index.adoc
> @@ -0,0 +1,7 @@
> += Getting Started
> +:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). Ready to get started with Spectrum OS? After installing you can create VMs and then configure each one.
> +:page-nav_order: 3
> +:page-has_children: true
> +
> +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/running-vms.adoc b/Documentation/getting-started/running-vms.adoc
> similarity index 93%
> rename from Documentation/running-vms.adoc
> rename to Documentation/getting-started/running-vms.adoc
> index d0d3f99..9073e3c 100644
> --- a/Documentation/running-vms.adoc
> +++ b/Documentation/getting-started/running-vms.adoc
> @@ -1,5 +1,5 @@
>  = Running VMs
> -:page-parent: Reference
> +:page-parent: Getting Started
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/user-partition.adoc b/Documentation/getting-started/user-partition.adoc
> similarity index 80%
> rename from Documentation/user-partition.adoc
> rename to Documentation/getting-started/user-partition.adoc
> index 73bc0d0..a33d7fc 100644
> --- a/Documentation/user-partition.adoc
> +++ b/Documentation/getting-started/user-partition.adoc
> @@ -1,11 +1,13 @@
> -= The User Partition
> -:page-parent: Explanation
> += User Partition
> +:page-parent: Getting Started
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>  
>  The Spectrum host system is immutable, so configuration and user data
> -lives on a separate partition.  The host system discovers the user
> +lives on a separate partition.
> +
> +The host system discovers the user
>  partition by looking for the special partition type
>  `9293e1ff-cee4-4658-88be-898ec863944f`.  This behavior can be
>  overridden with the `ext` parameter on the host's kernel command line,
> diff --git a/Documentation/how-to.adoc b/Documentation/how-to.adoc
> index f43fa13..98cc842 100644
> --- a/Documentation/how-to.adoc
> +++ b/Documentation/how-to.adoc
> @@ -1,4 +1,5 @@
>  = How-to Guides
> +:page-nav_exclude: true
>  :page-has_children: true
>  :page-nav_order: 2
>  
> diff --git a/Documentation/index.adoc b/Documentation/index.adoc
> index 3079847..d26676b 100644
> --- a/Documentation/index.adoc
> +++ b/Documentation/index.adoc
> @@ -1,13 +1,23 @@
> -= Spectrum Docs
> += Spectrum Documentation
>  :page-nav_exclude: true
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
> +// SPDX-FileCopyrightText: 2022 Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>  
> -Spectrum is a compartmentalized operating system.
> +== Spectrum Project
>  
> -If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting
> -Spectrum].
> +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 easier to use and maintain than other such systems. For more information on the Spectrum project, see https://spectrum-os.org/.

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.

>  
> -To learn about what Spectrum is and how it's implemented, start with
> -the xref:architecture.adoc[architecture overview].
> +Spectrum is made of free and open source software. It is free for anyone to use, modify, and distribute. If you want to be involved with the Spectrum project, see https://spectrum-os.org/contributing.html.
> +
> +The Spectrum project source code is https://spectrum-os.org/git/spectrum.
> +
> +== Spectrum OS
> +
> +Spectrum is an in-development operating system that aims to afford its users security by compartmentalization, while also improving upon other similar projects by maintaining a high level of usability.

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?

> +
> +To learn about what Spectrum OS is and how it's implemented, start with
> +the xref:about/architecture.adoc[architecture overview].
> +
> +If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run].
> diff --git a/Documentation/b4.adoc b/Documentation/installation/b4.adoc
> similarity index 96%
> rename from Documentation/b4.adoc
> rename to Documentation/installation/b4.adoc
> index 2519894..1ba87b2 100644
> --- a/Documentation/b4.adoc
> +++ b/Documentation/installation/b4.adoc
> @@ -1,5 +1,6 @@
>  = Installing and Configuring b4
> -:page-parent: Tutorials
> +:page-parent: Build and Run
> +:page-nav_order: 3
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc
> similarity index 90%
> rename from Documentation/binary-cache.adoc
> rename to Documentation/installation/binary-cache.adoc
> index 6e69b39..232f96c 100644
> --- a/Documentation/binary-cache.adoc
> +++ b/Documentation/installation/binary-cache.adoc
> @@ -1,10 +1,11 @@
> -= Setting Up the Binary Cache
> -:page-parent: How-to Guides
> += Setting Up Binary Cache
> +:page-parent: Build and Run
> +:page-nav_order: 1
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>  
> -Building Spectrum from source can take a very long time.  To avoid
> +Building Spectrum OS from source can take a very long time.  To avoid
>  having to wait when building the system to try it out or test patches,
>  an x86_64 binary cache service is available.  If configured to do so,
>  Nix will download build outputs from the cache, instead of building
> @@ -20,7 +21,7 @@ encounter any trouble with it.
>  The binary cache is currently not able to provide logs, due to a
>  https://github.com/NixOS/nix/pull/6051[Nix bug].
>  
> -== On NixOS
> +== For NixOS
>  
>  The following configuration adds the Spectrum binary cache as a
>  substituter, and tells Nix to trust builds signed with its public key.
> @@ -38,7 +39,7 @@ substituter, and tells Nix to trust builds signed with its public key.
>  }
>  ----
>  
> -== On Non-NixOS systems
> +== For Non-NixOS Systems
>  
>  Add the following configuration to /etc/nix/nix.conf:
>  
> diff --git a/Documentation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc
> similarity index 85%
> rename from Documentation/getting-spectrum.adoc
> rename to Documentation/installation/getting-spectrum.adoc
> index b3fa1ef..a0ea1c4 100644
> --- a/Documentation/getting-spectrum.adoc
> +++ b/Documentation/installation/getting-spectrum.adoc
> @@ -1,10 +1,11 @@
>  = Getting Spectrum
> -:page-parent: Tutorials
> +:page-parent: Build and Run
> +:page-nav_order: 2
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
>  
> -To get Spectrum, you need to build it from source.  As long as you're
> +To get Spectrum OS, you need to build it from source.  As long as you're
>  running Linuxfootnote:[Building from other operating systems might
>  work, but hasn't been tested.  Patches are welcome to support building
>  from other operating systems, as long as they're not too invasive.]
> @@ -17,7 +18,7 @@ lot of time waiting for builds.
>  
>  == Trying Spectrum
>  
> -If you want to try Spectrum out to get a feel for it, without
> +If you want to try Spectrum OS out to get a feel for it, without
>  installing it, you can run it in a development VM with some example
>  applications.
>  
> @@ -34,7 +35,7 @@ nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run'
>  This builds just enough of Spectrum to try it out in a VM, but it will
>  still take a very long time.
>  
> -== Building an installer
> +== Building Installer
>  
>  [source,shell]
>  ----
> @@ -48,7 +49,7 @@ named "result" will appear, pointing to a Spectrum USB installer
>  image.
>  
>  CAUTION: Spectrum is not yet suitable for real-world use.  Do not use
> -your Spectrum system for anything important or sensitive.  Spectrum is
> +your Spectrum OS for anything important or sensitive.  Spectrum is
>  currently missing many important security properties, and there is no
>  procedure for updating to new versions of Spectrum -- you have to
>  reinstall.
> diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
> new file mode 100644
> index 0000000..99e9723
> --- /dev/null
> +++ b/Documentation/installation/index.adoc
> @@ -0,0 +1,18 @@
> += Build and Run
> +:description: How to download and install Spectrum OS.
> +:page-nav_order: 2
> +:page-has_children: true
> +
> +// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +To try Spectrum OS out or xref:../development/testing-patches.adoc[test patches], you need to build the system from the source.
> +
> +In order to speed up the build process, set up the binary cache. After building Spectrum OS, you can install and configure the b4 utility to be able to work with patches.
> +
> +
> +TIP: Note that Spectrum OS currently works only on x86-64. AAarch64 support is in development.
> +
> +Currently, there is no implementation for a software update.
> +
> +You can replace the installation with some other OS.

The information on this page feels very similar to the information on
the "Getting Spectrum" page.  Do you think we need both?

> diff --git a/Documentation/reference.adoc b/Documentation/reference.adoc
> index 44b359d..55259ea 100644
> --- a/Documentation/reference.adoc
> +++ b/Documentation/reference.adoc
> @@ -1,6 +1,5 @@
>  = Reference
> -:page-has_children: true
> -:page-nav_order: 3
> +:page-nav_exclude: true
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/tutorials.adoc b/Documentation/tutorials.adoc
> index cd1fb12..fcef31b 100644
> --- a/Documentation/tutorials.adoc
> +++ b/Documentation/tutorials.adoc
> @@ -1,6 +1,5 @@
>  = Tutorials
> -:page-nav_order: 1
> -:page-has_children: true
> +:page-nav_exclude: true
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
>  // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> -- 
> 2.34.1

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [PATCH] Docs: new structure
@ 2022-09-06 13:55 Jenni Nikolaenko
  2022-09-19  9:30 ` Alyssa Ross
  0 siblings, 1 reply; 12+ messages in thread
From: Jenni Nikolaenko @ 2022-09-06 13:55 UTC (permalink / raw)
  To: devel; +Cc: Jenni Nikolaenko

Create separate folders for new parent pages, update Introduction page,
remove a and the articles from titles, quick check text for simple english

Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
---
 Documentation/{ => about}/architecture.adoc   | 19 ++++-----
 Documentation/about/index.adoc                | 21 ++++++++++
 .../decisions/001-host-update-mechanism.adoc  |  2 +-
 .../decisions/002-install-options.adoc        |  4 +-
 Documentation/decisions/003-partitioning.adoc |  2 +-
 .../004-data-at-rest-encryption.adoc          |  2 +-
 .../005-virtual-machine-monitor.adoc          |  2 +-
 .../decisions/006-drivers-on-host.adoc        |  2 +-
 .../decisions/007-usb-virtual-machines.adoc   |  2 +-
 ...008-inter-vm-communication-mechanisms.adoc |  2 +-
 Documentation/decisions/index.adoc            |  2 +-
 .../building-documentation.adoc               | 10 ++---
 .../{ => development}/debugging.adoc          |  7 ++--
 .../{ => development}/first-patch.adoc        | 28 +++++++------
 Documentation/development/index.adoc          | 17 ++++++++
 Documentation/{ => development}/replying.adoc |  4 +-
 .../{ => development}/reviewing-patches.adoc  |  4 +-
 .../{ => development}/testing-patches.adoc    | 42 ++++++++-----------
 .../{ => development}/uuid-reference.adoc     |  4 +-
 Documentation/explanation.adoc                |  3 +-
 .../{ => getting-started}/creating-vms.adoc   |  2 +-
 Documentation/getting-started/index.adoc      |  7 ++++
 .../{ => getting-started}/running-vms.adoc    |  2 +-
 .../{ => getting-started}/user-partition.adoc |  8 ++--
 Documentation/how-to.adoc                     |  1 +
 Documentation/index.adoc                      | 22 +++++++---
 Documentation/{ => installation}/b4.adoc      |  3 +-
 .../{ => installation}/binary-cache.adoc      | 11 ++---
 .../{ => installation}/getting-spectrum.adoc  | 11 ++---
 Documentation/installation/index.adoc         | 18 ++++++++
 Documentation/reference.adoc                  |  3 +-
 Documentation/tutorials.adoc                  |  3 +-
 32 files changed, 171 insertions(+), 99 deletions(-)
 rename Documentation/{ => about}/architecture.adoc (84%)
 create mode 100644 Documentation/about/index.adoc
 rename Documentation/{ => development}/building-documentation.adoc (85%)
 rename Documentation/{ => development}/debugging.adoc (92%)
 rename Documentation/{ => development}/first-patch.adoc (83%)
 create mode 100644 Documentation/development/index.adoc
 rename Documentation/{ => development}/replying.adoc (93%)
 rename Documentation/{ => development}/reviewing-patches.adoc (89%)
 rename Documentation/{ => development}/testing-patches.adoc (62%)
 rename Documentation/{ => development}/uuid-reference.adoc (98%)
 rename Documentation/{ => getting-started}/creating-vms.adoc (98%)
 create mode 100644 Documentation/getting-started/index.adoc
 rename Documentation/{ => getting-started}/running-vms.adoc (93%)
 rename Documentation/{ => getting-started}/user-partition.adoc (80%)
 rename Documentation/{ => installation}/b4.adoc (96%)
 rename Documentation/{ => installation}/binary-cache.adoc (90%)
 rename Documentation/{ => installation}/getting-spectrum.adoc (85%)
 create mode 100644 Documentation/installation/index.adoc

diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc
similarity index 84%
rename from Documentation/architecture.adoc
rename to Documentation/about/architecture.adoc
index 1c4307b..db82d60 100644
--- a/Documentation/architecture.adoc
+++ b/Documentation/about/architecture.adoc
@@ -1,17 +1,16 @@
 = Architecture
-:page-parent: Explanation
+:page-parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-FileCopyrightText: 2022 Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-== Introduction
+Spectrum OS is based on the principle of security by compartmentalization.
 
-Spectrum is based on the principle of security by
-compartmentalization.  The high level stack is illustrated in the
-following diagram:
+The high level stack is illustrated in the following diagram:
 
-image::diagrams/stack.svg[]
+image::../diagrams/stack.svg[]
 
 The default set of virtual machines includes two application VMs,
 _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web
@@ -26,7 +25,7 @@ https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant
 decisions] are xref:decisions/index.adoc[recorded] as lightweight
 https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs].
 
-== The Spectrum host system
+== Spectrum Host System
 
 Compartmentalization is implemented using
 https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines.
@@ -35,7 +34,7 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual
 Machine] (KVM) to provide lightweight, hardware-accelerated VMs.
 
 While Linux (including KVM) is portable between many hardware architectures,
-cloud-hypervisor supports only x86_64 and aarch64.  Spectrum currently only
+cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only
 works on x86_64, but aarch64 support is in development.
 
 https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service
@@ -44,7 +43,7 @@ and service scripts.
 
 https://wayland.freedesktop.org/[Wayland] is used for window management and
 display.  The Wayland architecture is well documented
-https://wayland.freedesktop.org/architecture.html[here].  The host provides only
+https://wayland.freedesktop.org/architecture.html[here]. The host provides only
 a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used
 for interacting with VM consoles.  In future it will be possible for application
 VMs to display windows on the single Wayland compositor on the host system,
@@ -57,7 +56,7 @@ https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion
 and security hardening on memory allocation].  Kernel hardening will be
 investigated in future.
 
-== Exploring the Spectrum dependency tree
+== Spectrum Dependency Tree
 
 For a detailed, interactive view of dependencies, use
 https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository:
diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc
new file mode 100644
index 0000000..a882852
--- /dev/null
+++ b/Documentation/about/index.adoc
@@ -0,0 +1,21 @@
+= About Spectrum OS
+:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.
+:page-nav_order: 1
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Spectrum is a Linux-based system, derived from NixOS. This gives an actively-developed base with good hardware support, powerful and optimised compartmentalization primitives in KVM, and the reproducible packaging and configuration system that is important for a maintainable compartmentalized system.
+
+== Why Spectrum
+
+There are several features that make Spectrum OS unique:
+
+* User data and applications are managed centrally, while remaining isolated.
+That means that the system can be backed up and managed as a whole, rather than mixed up in several dozen VMs.
+
+* The host system and isolated environments are managed declaratively and reproducibly using the Nix package manager.
+This can save the user the burden of maintaining many different virtual computers, allowing finer-grained resource access controls and making it possible to verify the software running across all environments.
+
+TIP: If you are interested in why we do something _this_ way instead of _that_ way, see xref:../decisions/index.adoc[Architecture Decision Records].
diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc
index 574deb4..7032146 100644
--- a/Documentation/decisions/001-host-update-mechanism.adoc
+++ b/Documentation/decisions/001-host-update-mechanism.adoc
@@ -1,6 +1,6 @@
 = 001 Host Update Mechanism
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc
index 4412b53..a7c4175 100644
--- a/Documentation/decisions/002-install-options.adoc
+++ b/Documentation/decisions/002-install-options.adoc
@@ -1,6 +1,6 @@
-= 002 Install options
+= 002 Install Options
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc
index 8494ea4..b00f528 100644
--- a/Documentation/decisions/003-partitioning.adoc
+++ b/Documentation/decisions/003-partitioning.adoc
@@ -1,6 +1,6 @@
 = 003 Partitioning
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc
index 26fe273..27323db 100644
--- a/Documentation/decisions/004-data-at-rest-encryption.adoc
+++ b/Documentation/decisions/004-data-at-rest-encryption.adoc
@@ -1,6 +1,6 @@
 = 004 Data at Rest Encryption
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/005-virtual-machine-monitor.adoc b/Documentation/decisions/005-virtual-machine-monitor.adoc
index db81c72..df5a65e 100644
--- a/Documentation/decisions/005-virtual-machine-monitor.adoc
+++ b/Documentation/decisions/005-virtual-machine-monitor.adoc
@@ -1,6 +1,6 @@
 = 005 Virtual Machine Monitor
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc
index 872044e..86d3105 100644
--- a/Documentation/decisions/006-drivers-on-host.adoc
+++ b/Documentation/decisions/006-drivers-on-host.adoc
@@ -1,6 +1,6 @@
 = 006 Drivers on Host
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/007-usb-virtual-machines.adoc b/Documentation/decisions/007-usb-virtual-machines.adoc
index 3bdf78b..24dac65 100644
--- a/Documentation/decisions/007-usb-virtual-machines.adoc
+++ b/Documentation/decisions/007-usb-virtual-machines.adoc
@@ -1,6 +1,6 @@
 = 007 USB Virtual Machine
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
index a1b7d49..9fce4ef 100644
--- a/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
+++ b/Documentation/decisions/008-inter-vm-communication-mechanisms.adoc
@@ -1,6 +1,6 @@
 = 008 Inter-VM Communication Mechanisms
 :page-parent: Architecture Decision Records
-:page-grand_parent: Explanation
+:page-grand_parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/decisions/index.adoc b/Documentation/decisions/index.adoc
index 772f382..4f3a7e1 100644
--- a/Documentation/decisions/index.adoc
+++ b/Documentation/decisions/index.adoc
@@ -1,6 +1,6 @@
 = Architecture Decision Records
 :page-has_children: true
-:page-parent: Explanation
+:page-parent: About Spectrum OS
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/building-documentation.adoc b/Documentation/development/building-documentation.adoc
similarity index 85%
rename from Documentation/building-documentation.adoc
rename to Documentation/development/building-documentation.adoc
index b491105..da5fa8c 100644
--- a/Documentation/building-documentation.adoc
+++ b/Documentation/development/building-documentation.adoc
@@ -1,5 +1,5 @@
-= Building the Documentation
-:page-parent: Tutorials
+= Building Documentation
+:page-parent: Development
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -47,6 +47,6 @@ IMPORTANT: Jekyll doesn't handle rendering of the draw.io diagrams, so
 if you modify any of those, or add new ones, you'll have to run
 `scripts/build.sh` again to do a full rebuild of the site.
 
-Once you've made your changes to the documentation, see
-xref:first-patch.adoc[Sending Your First Patch] for information
-about how to submit them for review.
+Once you made your changes to the documentation, see
+xref:first-patch.adoc[Patching] for information
+on how to submit your patch for review.
diff --git a/Documentation/debugging.adoc b/Documentation/development/debugging.adoc
similarity index 92%
rename from Documentation/debugging.adoc
rename to Documentation/development/debugging.adoc
index 3871a7c..6e529a9 100644
--- a/Documentation/debugging.adoc
+++ b/Documentation/development/debugging.adoc
@@ -1,7 +1,6 @@
-= Debugging Spectrum
-:page-parent: Explanation
-:toc:
-:toclevels: 1
+= Debugging
+:page-parent: Development
+:page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/first-patch.adoc b/Documentation/development/first-patch.adoc
similarity index 83%
rename from Documentation/first-patch.adoc
rename to Documentation/development/first-patch.adoc
index 30672b9..7b8dd1d 100644
--- a/Documentation/first-patch.adoc
+++ b/Documentation/development/first-patch.adoc
@@ -1,11 +1,12 @@
-= Sending Your First Patch
-:page-parent: Tutorials
+= Patching
+:page-parent: Development
+:page-nav_order: 1
+:page-has_children: true
+:toc: preamble
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-== Prerequisites
-
 This tutorial assumes that you already have basic
 https://git-scm.com/[git] experience.
 
@@ -14,10 +15,10 @@ https://spectrum-os.org/git/[Spectrum source tree].  You'll also need
 to have configured `git send-email` — a guide for this can be found at
 https://git-send-email.io/.
 
-== Making your changes
+== Making Changes
 
-If you've worked on any git repository before, the process for making
-your changes will probably be very familiar.
+If you worked on any git repository before, the process for making
+your changes will be very familiar.
 
 1. Create a branch for your changes:
 +
@@ -39,7 +40,7 @@ indicates your acceptance of the
 https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's
 Certificate of Origin], which is mandatory for Spectrum patches.
 
-== Submitting changes
+== Submitting Changes
 
 Once you're happy with how the commits on your branch look, run:
 
@@ -64,13 +65,14 @@ message that will be sent before all of your patches.
 
 Once your patch has been submitted, wait for it to be reviewed.
 Feedback, if any, will be sent as email replies to your submitted
-patch.  You can respond to feedback in your mail client.  Please use
-the Reply All button to ensure that your messages are sent to the
+patch.  You can respond to feedback in your mail client.
+
+Use the *Reply All* button to sent your messages to the
 mailing list as well as to the person who sent the feedback.
 
-If you need to make changes to your patch, and submit a new version,
+If you need to make changes to your patch and submit a new version,
 use https://git-rebase.io/[`git rebase`] to create a new version of
-your patch(es), and submit it like this:
+your patch(es) and then submit it like this:
 
 [source,shell]
 ----
@@ -81,7 +83,7 @@ The added `-v2` flag indicates that this is version two of your
 patch set.  If your patches require more rounds of changes, submit
 subsequent rounds with `-v3`, `-v4`, etc. as appropriate.
 
-If you'd like to describe what has changed from the previous version
+If you would like to describe what has changed from the previous version
 of your patches, you can do so in a xref:cover-letter[cover letter]
 as described above.
 
diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
new file mode 100644
index 0000000..471daf7
--- /dev/null
+++ b/Documentation/development/index.adoc
@@ -0,0 +1,17 @@
+= Development
+:description: Development progress, general development practices
+:page-nav_order: 4
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Spectrum is free software, currently under active development.
+
+== Developer Setup
+
+Before starting, make sure you are familiar with https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] and the https://nixos.org/manual/nix/stable/introduction.html[Nix package manager].
+
+== Mailing Lists
+
+The Spectrum project runs several https://spectrum-os.org/mailman3/lists/?all-lists[mailing lists] on which you can ask your questions or help other people with the questions they have. All the Spectrum developers as well as many long time Linux and Spectrum users are on the lists.
diff --git a/Documentation/replying.adoc b/Documentation/development/replying.adoc
similarity index 93%
rename from Documentation/replying.adoc
rename to Documentation/development/replying.adoc
index bb8e31a..05740a0 100644
--- a/Documentation/replying.adoc
+++ b/Documentation/development/replying.adoc
@@ -1,5 +1,7 @@
 = Replying to Messages in the Mailing List Archives
-:page-parent: Tutorials
+:page-parent: Patching
+:page-grand_parent: Development
+:page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc
similarity index 89%
rename from Documentation/reviewing-patches.adoc
rename to Documentation/development/reviewing-patches.adoc
index 63ff24e..c8c971f 100644
--- a/Documentation/reviewing-patches.adoc
+++ b/Documentation/development/reviewing-patches.adoc
@@ -1,5 +1,7 @@
 = Reviewing Patches
-:page-parent: How-to Guides
+:page-parent: Patching
+:page-grand_parent: Development
+:page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/testing-patches.adoc b/Documentation/development/testing-patches.adoc
similarity index 62%
rename from Documentation/testing-patches.adoc
rename to Documentation/development/testing-patches.adoc
index 8ba7804..99adfd2 100644
--- a/Documentation/testing-patches.adoc
+++ b/Documentation/development/testing-patches.adoc
@@ -1,5 +1,8 @@
 = Testing Patches
-:page-parent: How-to Guides
+:page-parent: Patching
+:page-grand_parent: Development
+:page-nav_order: 1
+:toc: preamble
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -8,52 +11,41 @@ Potential changes to Spectrum are posted to and discussed on the
 https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org]
 mailing list.
 
-== Apply the patch
+== Apply Patch
 
 If you haven't already, you'll first need to xref:b4.adoc[install and
 configure] https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4].
 Then:
 
-. Find the patch series you want to test on
-  https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox].
-. Navigate to the "permalink" page for any patch in the series.
-. Copy the Message-Id for the patch, as shown on the permalink page, e.g.
-  \20220511092352.70E54C980@atuin.qyliss.net.
-. In a checkout of the appropriate git repository
-  (https://spectrum-os.org/git/spectrum[Spectrum] or
-  https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), Run `b4 am`
-  with the patch's Message-Id to download all the patches in the
-  series into a file.
+1. Find the patch series you want to test on https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox].
+2. Navigate to the "permalink" page for any patch in the series.
+3. Copy the Message-Id for the patch, as shown on the permalink page, e.g.  \20220511092352.70E54C980@atuin.qyliss.net.
+4. In a checkout of the appropriate git repository   (https://spectrum-os.org/git/spectrum[Spectrum] or   https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), run `b4 am` with the patch's Message-Id to download all the patches in the series into a file.
 +
-[example]
 [source,shell]
 ----
 b4 am 20220511092352.70E54C980@atuin.qyliss.net
 ----
-
-. b4 will indicate the file name it has downloaded the patches into
-  with a line like:
+b4 will indicate the file name it has downloaded the patches into with a line like:
 +
-[example]
-[listing]
+[source,shell]
+----
 Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
+----
+5. Run `git am` on that file to apply the patches, for example:
 +
-Run `git am` on that file to apply the patches, for example:
-+
-[example]
 [source,shell]
 ----
 git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
 ----
 
-== Post your test results
+== Post Your Results
 
 When you've tested a patch, it's really helpful to
 xref:replying.adoc[reply] with your test results.
 
-If the patch worked for you, please reply to it and include a line
-like the following, separated from any reply text:
-
+If the patch worked for you, please reply to it and include a line like the following, separated from any reply text:
+[source,shell]
 ----
 Tested-by: John Smith <john@example.com>
 ----
diff --git a/Documentation/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc
similarity index 98%
rename from Documentation/uuid-reference.adoc
rename to Documentation/development/uuid-reference.adoc
index 4b0b481..0eccc82 100644
--- a/Documentation/uuid-reference.adoc
+++ b/Documentation/development/uuid-reference.adoc
@@ -1,5 +1,5 @@
 = UUID Reference
-:page-parent: Reference
+:page-parent: Development
 :toc: preamble
 :toclevels: 1
 
@@ -40,7 +40,7 @@ xref:user-partition.adoc[Spectrum user partition].
 
 === `56a3bbc3-aefa-43d9-a64d-7b3fd59bbc4e`
 
-https://github.com/endlessm/eos-installer["eosimages"] partition on the 
+https://github.com/endlessm/eos-installer["eosimages"] partition on the
 Spectrum combined live system / installer image.
 
 == Combined Image Partition IDs
diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc
index b39cc6d..f682129 100644
--- a/Documentation/explanation.adoc
+++ b/Documentation/explanation.adoc
@@ -1,6 +1,5 @@
 = Explanation
-:page-has_children: true
-:page-nav_order: 4
+:page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/creating-vms.adoc b/Documentation/getting-started/creating-vms.adoc
similarity index 98%
rename from Documentation/creating-vms.adoc
rename to Documentation/getting-started/creating-vms.adoc
index d967098..e06be85 100644
--- a/Documentation/creating-vms.adoc
+++ b/Documentation/getting-started/creating-vms.adoc
@@ -1,5 +1,5 @@
 = Creating VMs
-:page-parent: Reference
+:page-parent: Getting Started
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc
new file mode 100644
index 0000000..1b468ab
--- /dev/null
+++ b/Documentation/getting-started/index.adoc
@@ -0,0 +1,7 @@
+= Getting Started
+:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). Ready to get started with Spectrum OS? After installing you can create VMs and then configure each one.
+:page-nav_order: 3
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/running-vms.adoc b/Documentation/getting-started/running-vms.adoc
similarity index 93%
rename from Documentation/running-vms.adoc
rename to Documentation/getting-started/running-vms.adoc
index d0d3f99..9073e3c 100644
--- a/Documentation/running-vms.adoc
+++ b/Documentation/getting-started/running-vms.adoc
@@ -1,5 +1,5 @@
 = Running VMs
-:page-parent: Reference
+:page-parent: Getting Started
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/user-partition.adoc b/Documentation/getting-started/user-partition.adoc
similarity index 80%
rename from Documentation/user-partition.adoc
rename to Documentation/getting-started/user-partition.adoc
index 73bc0d0..a33d7fc 100644
--- a/Documentation/user-partition.adoc
+++ b/Documentation/getting-started/user-partition.adoc
@@ -1,11 +1,13 @@
-= The User Partition
-:page-parent: Explanation
+= User Partition
+:page-parent: Getting Started
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
 The Spectrum host system is immutable, so configuration and user data
-lives on a separate partition.  The host system discovers the user
+lives on a separate partition.
+
+The host system discovers the user
 partition by looking for the special partition type
 `9293e1ff-cee4-4658-88be-898ec863944f`.  This behavior can be
 overridden with the `ext` parameter on the host's kernel command line,
diff --git a/Documentation/how-to.adoc b/Documentation/how-to.adoc
index f43fa13..98cc842 100644
--- a/Documentation/how-to.adoc
+++ b/Documentation/how-to.adoc
@@ -1,4 +1,5 @@
 = How-to Guides
+:page-nav_exclude: true
 :page-has_children: true
 :page-nav_order: 2
 
diff --git a/Documentation/index.adoc b/Documentation/index.adoc
index 3079847..d26676b 100644
--- a/Documentation/index.adoc
+++ b/Documentation/index.adoc
@@ -1,13 +1,23 @@
-= Spectrum Docs
+= Spectrum Documentation
 :page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-FileCopyrightText: 2022 Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-Spectrum is a compartmentalized operating system.
+== Spectrum Project
 
-If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting
-Spectrum].
+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 easier to use and maintain than other such systems. For more information on the Spectrum project, see https://spectrum-os.org/.
 
-To learn about what Spectrum is and how it's implemented, start with
-the xref:architecture.adoc[architecture overview].
+Spectrum is made of free and open source software. It is free for anyone to use, modify, and distribute. If you want to be involved with the Spectrum project, see https://spectrum-os.org/contributing.html.
+
+The Spectrum project source code is https://spectrum-os.org/git/spectrum.
+
+== Spectrum OS
+
+Spectrum is an in-development operating system that aims to afford its users security by compartmentalization, while also improving upon other similar projects by maintaining a high level of usability.
+
+To learn about what Spectrum OS is and how it's implemented, start with
+the xref:about/architecture.adoc[architecture overview].
+
+If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run].
diff --git a/Documentation/b4.adoc b/Documentation/installation/b4.adoc
similarity index 96%
rename from Documentation/b4.adoc
rename to Documentation/installation/b4.adoc
index 2519894..1ba87b2 100644
--- a/Documentation/b4.adoc
+++ b/Documentation/installation/b4.adoc
@@ -1,5 +1,6 @@
 = Installing and Configuring b4
-:page-parent: Tutorials
+:page-parent: Build and Run
+:page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc
similarity index 90%
rename from Documentation/binary-cache.adoc
rename to Documentation/installation/binary-cache.adoc
index 6e69b39..232f96c 100644
--- a/Documentation/binary-cache.adoc
+++ b/Documentation/installation/binary-cache.adoc
@@ -1,10 +1,11 @@
-= Setting Up the Binary Cache
-:page-parent: How-to Guides
+= Setting Up Binary Cache
+:page-parent: Build and Run
+:page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-Building Spectrum from source can take a very long time.  To avoid
+Building Spectrum OS from source can take a very long time.  To avoid
 having to wait when building the system to try it out or test patches,
 an x86_64 binary cache service is available.  If configured to do so,
 Nix will download build outputs from the cache, instead of building
@@ -20,7 +21,7 @@ encounter any trouble with it.
 The binary cache is currently not able to provide logs, due to a
 https://github.com/NixOS/nix/pull/6051[Nix bug].
 
-== On NixOS
+== For NixOS
 
 The following configuration adds the Spectrum binary cache as a
 substituter, and tells Nix to trust builds signed with its public key.
@@ -38,7 +39,7 @@ substituter, and tells Nix to trust builds signed with its public key.
 }
 ----
 
-== On Non-NixOS systems
+== For Non-NixOS Systems
 
 Add the following configuration to /etc/nix/nix.conf:
 
diff --git a/Documentation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc
similarity index 85%
rename from Documentation/getting-spectrum.adoc
rename to Documentation/installation/getting-spectrum.adoc
index b3fa1ef..a0ea1c4 100644
--- a/Documentation/getting-spectrum.adoc
+++ b/Documentation/installation/getting-spectrum.adoc
@@ -1,10 +1,11 @@
 = Getting Spectrum
-:page-parent: Tutorials
+:page-parent: Build and Run
+:page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
 
-To get Spectrum, you need to build it from source.  As long as you're
+To get Spectrum OS, you need to build it from source.  As long as you're
 running Linuxfootnote:[Building from other operating systems might
 work, but hasn't been tested.  Patches are welcome to support building
 from other operating systems, as long as they're not too invasive.]
@@ -17,7 +18,7 @@ lot of time waiting for builds.
 
 == Trying Spectrum
 
-If you want to try Spectrum out to get a feel for it, without
+If you want to try Spectrum OS out to get a feel for it, without
 installing it, you can run it in a development VM with some example
 applications.
 
@@ -34,7 +35,7 @@ nix-shell -I nixpkgs=../../../nixpkgs-spectrum --run 'make run'
 This builds just enough of Spectrum to try it out in a VM, but it will
 still take a very long time.
 
-== Building an installer
+== Building Installer
 
 [source,shell]
 ----
@@ -48,7 +49,7 @@ named "result" will appear, pointing to a Spectrum USB installer
 image.
 
 CAUTION: Spectrum is not yet suitable for real-world use.  Do not use
-your Spectrum system for anything important or sensitive.  Spectrum is
+your Spectrum OS for anything important or sensitive.  Spectrum is
 currently missing many important security properties, and there is no
 procedure for updating to new versions of Spectrum -- you have to
 reinstall.
diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
new file mode 100644
index 0000000..99e9723
--- /dev/null
+++ b/Documentation/installation/index.adoc
@@ -0,0 +1,18 @@
+= Build and Run
+:description: How to download and install Spectrum OS.
+:page-nav_order: 2
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Jenni Nikko <evgeniia.nikolaenko@unikie.com>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+To try Spectrum OS out or xref:../development/testing-patches.adoc[test patches], you need to build the system from the source.
+
+In order to speed up the build process, set up the binary cache. After building Spectrum OS, you can install and configure the b4 utility to be able to work with patches.
+
+
+TIP: Note that Spectrum OS currently works only on x86-64. AAarch64 support is in development.
+
+Currently, there is no implementation for a software update.
+
+You can replace the installation with some other OS.
diff --git a/Documentation/reference.adoc b/Documentation/reference.adoc
index 44b359d..55259ea 100644
--- a/Documentation/reference.adoc
+++ b/Documentation/reference.adoc
@@ -1,6 +1,5 @@
 = Reference
-:page-has_children: true
-:page-nav_order: 3
+:page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/tutorials.adoc b/Documentation/tutorials.adoc
index cd1fb12..fcef31b 100644
--- a/Documentation/tutorials.adoc
+++ b/Documentation/tutorials.adoc
@@ -1,6 +1,5 @@
 = Tutorials
-:page-nav_order: 1
-:page-has_children: true
+:page-nav_exclude: true
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
-- 
2.34.1




^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2022-11-08 15:05 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <RE: [PATCH] Docs: new structure>
2022-10-28 11:05 ` [PATCH] Docs: new structure 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
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
2022-10-28 11:22   ` Jenni Nikolaenko

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