Docs polishing

General Discussion
1

Took these notes about little typos and things while reading the docs. I had to drop my patch effort but figured the community might as well have it. They could be something easy for someone to run through as a first contribution.

There’s a few examples of how I did the PRs.

Choosing your hardware
Certified hardware

  • Requirements, “must be be available”

Downloading, installing, and upgrading Qubes
Installation guide

Copying the ISO onto the installation medium:

  • “We strongly recommended making …” → recommend

Getting to the boot screen:

  • “is may be called”
  • “To give you and idea of”

Localization:

  • “You can have as many keyboard layout and …”

Installation destination:

  • “We strongly recommended making …” → recommend

Initial Setup:

  • “Enabling system and template updates …” → Enable, for consistency

Get Started:

  • “Find out Getting Started …” → how to get started

Getting help:

  • “… accurate, comprehensive useful and …” → comprehensive, useful and

Downloading, installing, and upgrading Qubes
Supported releases

Qubes OS:

  • Release 4.3, remove milestone link, obsolete.

Downloading, installing, and upgrading Qubes
Testing new releases and updates

Updates:

  • “that is up the …” → up to the

Templates
Templates

Note on treating app qubes’ root filesystem non-persistence …:

  • “and surely many others places” → other
  • “might got maliciously modified” → might be, might have gotten

Project security
Verifying signatures

Qubes Master Signing Key:

  • “many Qubes team member keys” → any?

cryptographic hash values:

  • “which can find” → which you can find
  • “and you can always” → you can always

I have another problem that isn’t mentioned here:

  • “Still have question?” → Still have a question?

Releases
Version scheme

Lead:

  • “and major release are” → releases

Release schedule:

  • “and tested by wider user base.” → a wider

Bug priorities:

  • “only last resort option” → a last resort
  • “existence of such bugs do not” → does not, 2x
  • “be considered final” → from being considered, 2x
  • “All above is about” → All of the above
  • “after first” → after the first

Git tags and branches:

  • “by tag containing” → by a tag containing
  • “by R tag.” → by an R tag
  • “in master branch.” → in the master branch
  • “depending on maintainer of repository.” → on the maintainer

Check installed version:

  • “in the Qubes Manager” → Qube Manager

Releases
Release checklist

On final release:

  • “update installationinstructions” → installation instructions

Developer documentation
General
How to edit the documentation

Security:

  • “prior to be merged” → being merged

Developer documentation
General
Documentation style guide

Headings:

  • “##h2” → ## h2 [confirm not intentional]

English language conventions:

  • “for the sake consistency” → for the sake of

Do not duplicate documentation:

  • “as some point” → at some point

Code
Source code

  • “GUI virtualization, Dom0 side” → GUI qube side

Code
Coding style

Rationale:

  • “back fired” → backfired
  • “sometime months” → sometimes months
  • “sometime years” → sometimes years
  • “lead to a real” → led to a real

General typographical conventions:

  • “for argument and variables” → arguments
  • “CRLF line endings (-).” → remove (-), or replace with (‘\r\n’)

File naming conventions:

  • “/etc/qubes-rpc/policy/” → /etc/qubes/policy.d/
  • “the current state of system” → of the system
  • “All base qubes-related file” → Qubes-related
  • “But generally, there is little excuse” → conformant alert

Source Code management (Git) guidelines:

  • “for Qubes project.” → the Qubes project

Security coding guidelines:

  • “Any input that comes from … entity” → an … entity
  • “read from untrusted party” → an untrusted party
  • “Use others variables” → other

Python-specific guidelines:

  • “unless they were” → unless they are

C and C++ specific guidelines:

  • “Think about classes hierarchy” → the class hierarchy

Bash-specific guidelines:

  • “in Windows admin domain” → a Windows admin domain
  • “Windows gui domain” → GUI

Code
Code signing

Generating a Key:

  • Heading to sentence case.

Upload the Key:

  • Heading to sentence case.
  • “last 8 hex digits” → last 16, or last 8 bytes in hexadecimal
  • Remove duplicate example.

Using PGP with Git:

  • “which you like to” → would like to

GitHub Signature Verification (optional):

  • Heading to sentence case.
  • Confirm links, SSH mention probably wrong.

Code Signature Checks:

  • Heading to sentence case.
  • “using the any key” → using any key

Using PGP with Email:

  • Heading to sentence case.

System
GUI virtualization

Window content updates implementation:

  • “to the GUI daemon using using the” → deduplicate using
  • “mnfs” → mfns
  • “specified by qubes-guid” → qubes-guid, for consistency

Security markers on dom0 windows:

  • “to belong to other AppVM” → another AppVM

AppVM → GuiVM messages:

  • Stray tag

Templates
Minimal templates

Passwordless root:

  • “from which you can use execute root commands” → remove use

CentOS:

  • “to a standard Debian template” → remove paragraph, align with Fedora

Templates
Xfce templates

Installation:

  • “The Fedora Xfce templates can be installed …” → remove Fedora, general

Advanced topics
Volume backup and revert

  • “it’s volumes are stored” → its
  • “from the the above list” → deduplicate

Advanced topics
How to mount a Qubes partition from another OS

Accessing LVM Logical Volumes:

  • “for it’s LVM VG.” → its

Introduction
Code of Conduct

  • “the Marek” → remove article
6 Likes
2

Any GitHub account or other way of credit you’d like @cinderflash if someone picks these up?

1 Like
3

Thank you for asking, I’m not interested in credit. Fire away anyone who wants it. :slight_smile:

3 Likes
4

Thanks for this effort. I’m in process of working through these now.

Other users may not realise that the documentation is a community
effort. You can help us improve it by submitting a pull request.

If you prefer not to use GitHub, please PM me, or email me, with proposed
changes/improvements. I’ll credit you in any commit.

3 Likes
5

It’s possible to commit locally using git and send the git commit by email to someone :+1:

then someone can push it to GitHub

2 Likes
6

Though if I’m going to sign a commit, I’ll make sure I wrote it in the first place, and I’d prefer what the OP did here. YMMV

7

There is no trust difference IMO between doing all the changes from a list in a topic (this case), and signing someone’s commit that you reviewed carefully. The latter keeps the credits to the original author :+1:

Both are fine though, as long as the job is done :smiley:

8

Utilize chat GP to proof read each doc for normal spelling/grammar errors. It does a pretty good job and can save some time. Wont help with any substantive errors though.