Revamp "Documentation Guidelines"

- Update contribution steps and first two images
- Improve source formatting and consistency
- Add information
- Improve organization and add subheadings
- Clarify and improve wording

developer/general/doc-guidelines.md

@@ -65,20 +65,26 @@ please contribute it!
 
 A few notes before we get started:
 
-* Since Qubes is a security-oriented project, every documentation change will
+- Since Qubes is a security-oriented project, every documentation change will
-  be reviewed before it's accepted. This allows us to maintain quality control
+  be [reviewed](#security) before it's accepted. This allows us to maintain
-  and protect our users.
+  quality control and protect our users.
-* We don't want you to spend time and effort on a contribution that we can't
+
+- We don't want you to spend time and effort on a contribution that we can't
   accept. If your contribution would take a lot of time, please [file an
   issue](/doc/issue-tracking/) for it first so that we can make sure we're on
   the same page before significant works begins.
-* Alternatively, you may already have written content that doesn't conform to
+
+- Alternatively, you may already have written content that doesn't conform to
   these guidelines, but you'd be willing to modify it so that it does. In this
   case, you can still submit it by following the instructions below. Just make
   a note in your pull request (PR) that you're aware of the changes that need
   to be made and that you're just asking for the content to be reviewed before
   you spend time making those changes.
 
+- Finally, if you've written something that doesn't belong in qubes-doc but that
+  would be beneficial to the Qubes community, please consider adding it to the 
+  [external documentation](/doc/doc-guidelines/#core-vs-external-documentation).
+
 As mentioned above, we keep all the documentation in a dedicated [Git
 repository](https://github.com/QubesOS/qubes-doc) hosted on
 [GitHub](https://github.com/). Thanks to GitHub's interface, you can edit the
@@ -93,26 +99,29 @@ clone](https://guides.github.com/activities/forking/) the
 [submit a pull
 request](https://help.github.com/articles/using-pull-requests/).)
 
-Ok, let's start. Every documentation page has an "Edit this page" button. It
+Ok, let's start. Every documentation page has a "Page Source on GitHub" button.
-may be on the side (in the desktop layout):
+Depending on the size of your screen, it may either be on the side (larger
+screens) or on the bottom (smaller screens).
 
-[![edit-button-desktop](/attachment/doc/03-button2.png)](/attachment/doc/03-button2.png)
+[![page-source-button](/attachment/doc/doc-pr_01_page-source-button.png)](/attachment/doc/doc-pr_01_page-source-button.png)
 
-Or at the bottom (in the mobile layout):
+When you click on it, you'll be taken to the source file --- usually a Markdown
+(`.md`) file --- on GitHub. On this page, there will be a button to edit the
+file.
 
-[![edit-button-mobile](/attachment/doc/02-button1.png)](/attachment/doc/02-button1.png)
+[![github-edit](/attachment/doc/doc-pr_02_github-edit.png)](/attachment/doc/doc-pr_02_github-edit.png)
 
-When you click on it, you'll be prompted for your GitHub username and password
+You'll be prompted to sign in with your GitHub username and password
-(if you aren't already logged in). You can also create an account from here.
+(if you aren't already logged in). You can also create a free account from here.
 
-[![github-sign-in](/attachment/doc/04-sign-in.png)](/attachment/doc/04-sign-in.png)
+[![github-sign-in](/attachment/doc/doc-pr_03_sign-in.png)](/attachment/doc/doc-pr_03_sign-in.png)
 
 If this is your first contribution to the documentation, you need to "fork" the
 repository (make your own copy). It's easy --- just click the big green button
 on the next page. This step is only needed the first time you make a
 contribution.
 
-[![fork](/attachment/doc/05-fork.png)](/attachment/doc/05-fork.png)
+[![fork](/attachment/doc/doc-pr_04_fork.png)](/attachment/doc/doc-pr_04_fork.png)
 
 Now you can make your modifications. You can also preview the changes to see
 how they'll be formatted by clicking the "Preview changes" tab. If you want to
@@ -121,25 +130,27 @@ making formatting changes, please [render the site
 locally](https://github.com/QubesOS/qubesos.github.io#instructions) to verify
 that everything looks correct before submitting any changes.
 
-[![edit](/attachment/doc/06-edit.png)](/attachment/doc/06-edit.png)
+[![edit](/attachment/doc/doc-pr_05_edit.png)](/attachment/doc/doc-pr_05_edit.png)
 
 Once you're finished, describe your changes at the bottom and click "Propose
 file change".
 
-[![commit](/attachment/doc/07-commit-msg.png)](/attachment/doc/07-commit-msg.png)
+[![commit](/attachment/doc/doc-pr_06_commit-msg.png)](/attachment/doc/doc-pr_06_commit-msg.png)
 
 After that, you'll see exactly what modifications you've made. At this stage,
 those changes are still in your own copy of the documentation ("fork"). If
 everything looks good, send those changes to us by pressing the "Create pull
 request" button.
 
-[![pull-request](/attachment/doc/08-review-changes.png)](/attachment/doc/08-review-changes.png)
+[![pull-request](/attachment/doc/doc-pr_07_review-changes.png)](/attachment/doc/doc-pr_07_review-changes.png)
 
 You will be able to adjust the pull request message and title there. In most
 cases, the defaults are ok, so you can just confirm by pressing the "Create
-pull request" button again.
+pull request" button again. However, if you're not ready for your PR to be
+reviewed or merged yet, please [make a draft PR
+instead](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
 
-[![pull-request-confirm](/attachment/doc/09-create-pull-request.png)](/attachment/doc/09-create-pull-request.png)
+[![pull-request-confirm](/attachment/doc/doc-pr_08_create-pull-request.png)](/attachment/doc/doc-pr_08_create-pull-request.png)
 
 If any of your changes should be reflected in the [documentation index (a.k.a.
 table of contents)](/doc/) --- for example, if you're adding a new page,
@@ -152,9 +163,9 @@ you, which we'll post in a comment on your pull request. (GitHub will
 automatically notify you if we do.) If, for some reason, we can't accept your
 pull request, we'll post a comment explaining why we can't.
 
-[![done](/attachment/doc/10-done.png)](/attachment/doc/10-done.png)
+[![done](/attachment/doc/doc-pr_09_done.png)](/attachment/doc/doc-pr_09_done.png)
 
-## How to edit the documentation index
+### How to edit the documentation index
 
 The source file for the [documentation index (a.k.a. table of contents)](/doc/)
 lives here:
@@ -166,7 +177,7 @@ pull request (PR) adds, removes, or edits anything that should be reflected in
 the documentation index, please make sure you also submit an associated pull
 request against this file.
 
-## How to add images
+### How to add images
 
 To add an image to a page, use the following syntax in the main document. This
 will make the image a hyperlink to the image file, allowing the reader to click
@@ -352,7 +363,7 @@ Once you foo, make sure to close the baz before fooing the next bar.
 Subdividing the page into clearly-labeled sections for each version has several
 benefits:
 
-* It preserves good content for older (but still supported) versions. Many
+- It preserves good content for older (but still supported) versions. Many
   documentation contributors are also people who prefer to use the latest
   version. Many of them are tempted to *replace* existing content that applies
   to an older, supported version with content that applies only to the latest
@@ -368,9 +379,9 @@ benefits:
   version may have gone through several rounds of editing, review, and
   revision. It would be a tragedy for this content to vanish while the very set
   of users who most prize stability and reliability are depending on it.
-* It's easy for readers to quickly find the information they're looking for,
+- It's easy for readers to quickly find the information they're looking for,
   since they can go directly to the section that applies to their version.
-* It's hard for readers to miss information they need, since it's all in one
+- It's hard for readers to miss information they need, since it's all in one
   place. In the incorrect example, information that the reader needs could be
   in any paragraph in the entire document, and there's no way to tell without
   reading the entire page. In the correct example, the reader can simply skim
@@ -384,7 +395,7 @@ benefits:
   documentation for a version that *doesn't* change to stay the same, and we
   want the documentation for a version that *does* change to change along with
   the software.
-* It's easy for documentation contributors and maintainers to know which file
+- It's easy for documentation contributors and maintainers to know which file
   to edit and update, since there's only one page for all Qubes OS versions.
   Initially creating the new headings and duplicating content that applies to
   both is only a one-time cost for each page, and many pages don't even require
@@ -409,10 +420,14 @@ For further discussion about version-specific documentation in Qubes, see
 
 ## Style guidelines
 
-* Familiarize yourself with the terms defined in the
+### Correct use of terminology
-  [glossary](/doc/glossary/). Use these terms consistently and accurately
+
-  throughout your writing.
+Familiarize yourself with the terms defined in the [glossary](/doc/glossary/).
-* Syntactically distinguish variables in commands. For example, this is
+Use these terms consistently and accurately throughout your writing.
+
+### Variables in commands
+
+Syntactically distinguish variables in commands. For example, this is
 ambiguous:
 
     $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm
@@ -428,59 +443,94 @@ For further discussion about version-specific documentation in Qubes, see
 
 We have observed that many novices make the mistake of typing the surrounding
 angled brackets (`< >`) on the command line, even after substituting the
-  desired real value between them. Therefore, in documentation aimed at
+desired real value between them. Therefore, in documentation aimed at novices,
-  novices, we also recommend clarifying that the angled brackets should not be
+we also recommend clarifying that the angled brackets should not be typed. This
-  typed. This can be accomplished in one of several ways:
+can be accomplished in one of several ways:
 - Explicitly say something like "without the angled brackets."
 - Provide an example command using real values that excludes the angled
   brackets.
-  - If you know that almost all users will want to use (or should use) a
+- If you know that almost all users will want to use (or should use) a specific
-    specific command containing all real values and no variables, you might
+  command containing all real values and no variables, you might consider
-    consider providing exactly that command and forgoing the version with
+  providing exactly that command and forgoing the version with variables.
-    variables. Novices may not realize which parts of the command they can
+  Novices may not realize which parts of the command they can substitute with
-    substitute with different values, but if you've correctly judged that they
+  different values, but if you've correctly judged that they should use the
-    should use the command you've provided as is, then this shouldn't matter.
+  command you've provided as is, then this shouldn't matter.
 
 ## Markdown conventions
 
 All the documentation is written in Markdown for maximum accessibility. When
-making contributions, please try to observe the following style conventions:
+making contributions, please observe the following style conventions. If you're
+not familiar with Markdown syntax,
+[this](https://daringfireball.net/projects/markdown/) is a great resource.
 
-* Use spaces instead of tabs.
+### Indentation
-* Do not write HTML inside Markdown documents (except in rare, unavoidable
+
-  cases, such as alerts). In particular, never include HTML or CSS for styling,
+Use spaces instead of tabs. Each indentation step should be exactly two (2)
+spaces.
+
+### HTML and CSS
+
+Do not write HTML inside Markdown documents (except in rare, unavoidable cases,
+such as alerts). In particular, never include HTML or CSS for styling,
 formatting, or white space control. That belongs in the (S)CSS files instead.
-* Link only to images in
+
+### Image linking
+
+Link only to images in
 [qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see
 [instructions above](#how-to-add-images)). Do not link to images on other
 websites.
-* In order to enable offline browsing and automatic onion redirection, always
+
-  use relative (rather than absolute) links, e.g., `/doc/doc-guidelines/`
+### Relative vs. absolute links
-  instead of `https://www.qubes-os.org/doc/doc-guidelines/`. Examples of
+
-  exceptions:
+Always use relative rather than absolute paths for internal website links. For
-  * The signed plain text portions of [QSBs](/security/qsb/) and
+example, use `/doc/doc-guidelines/` instead of
-    [Canaries](/security/canary/)
+`https://www.qubes-os.org/doc/doc-guidelines/`. Places where it's fine to use
-  * URLs that appear inside code blocks (e.g., in comments and document
+absolute URLs:
-    templates)
+- External links
-  * Files like `README.md` and `CONTRIBUTING.md`
+- URLs that appear inside code blocks (e.g., in comments and document
-* Hard wrap Markdown lines at 80 characters, unless the line can't be broken
+  templates, and the plain text reproductions of [QSBs](/security/qsb/) and
-  (e.g., code or a URL).
+  [Canaries](/security/canary/)), since they're not hyperlinks
-* If appropriate, make numerals in numbered lists match between Markdown source
+- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part
-  and HTML output.
+  of the website itself but rather of the auxiliary infrastructure supporting
-  * Rationale: In the event that a user is required to read the Markdown source
+  the website.
-    directly, this will make it easier to follow, e.g., numbered steps in a set
+
-    of instructions.
+This rule is important, because using absolute URLs for internal website links
-* Use hanging indentations where appropriate.
+is known to break the following:
-* Do not use `h1` headings (single `#` or `======` underline). These are
+- Serving the website offline
+- Website localization
+- Generating offline documentation
+- Automatically redirecting Tor Browser visitors to the correct page on the
+  onion service mirror.
+
+### Source formatting and syntax
+
+- Do not use `h1` headings (single `#` or `======` underline). These are
   automatically generated from the `title:` line in the YAML frontmatter.
-* Use Atx-style headings: , `##h 2`, `### h3`, etc.
+
-* When writing code blocks, use [syntax
+- Use Atx-style headings: , `##h 2`, `### h3`, etc.
+
+- Use non-reference-style links like `[website](https://example.com/)`. Do
+  *not* use reference links like `[website][example]`, `[website][]` or
+  `[website]`.
+
+- If appropriate, make numerals in numbered lists match between Markdown source
+  and HTML output. (Rationale: In the event that a user is required to read the
+  Markdown source directly, this will make it easier to follow, e.g., numbered
+  steps in a set of instructions.)
+
+- When writing code blocks, use [syntax
   highlighting](https://github.github.com/gfm/#info-string) where
   [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers)
   and use `[...]` for anything omitted.
-* When providing command line examples:
+
-  * Tell the reader where to open a terminal (dom0 or a specific domU), and
+- Use hanging indentations where appropriate.
-    show the command along with its output (if any) in a code block, e.g.:
+
+### Writing command-line examples
+
+When providing command line examples:
+- Tell the reader where to open a terminal (dom0 or a specific domU), and show
+  the command along with its output (if any) in a code block, e.g.:
 
   ~~~markdown
   Open a terminal in dom0 and run:
@@ -491,10 +541,11 @@ making contributions, please try to observe the following style conventions:
   ```
   ~~~
 
- * Precede each command with the appropriate command prompt: At a minimum, the
+- Precede each command with the appropriate command prompt: At a minimum, the
-   prompt should contain a trailing `#` (for the user `root`) or `$` (for
+  prompt should contain a trailing `#` (for the user `root`) or `$` (for other
-   other users) on Linux systems and `>` on Windows systems, respectively.
+  users) on Linux systems and `>` on Windows systems, respectively.
- * Don't try to add comments inside the code block. For example, *don't* do
+
+- Don't try to add comments inside the code block. For example, *don't* do
   this:
 
    ~~~markdown
@@ -511,44 +562,56 @@ making contributions, please try to observe the following style conventions:
    The `#` symbol preceding each comment is ambiguous with a root command
    prompt. Instead, put your comments *outside* of the code block in normal
    prose.
-* Use non-reference-style links like `[website](https://example.com/)`. Do
-  *not* use reference links like `[website][example]`, `[website][]` or
-  `[website]`.
 
-([This](https://daringfireball.net/projects/markdown/) is a great source for
+### Line wrapping
-learning about Markdown.)
+
+Hard wrap Markdown lines at 80 characters, unless the line can't be broken
+(e.g., code or a URL).
 
 ## Coding conventions
 
-These conventions apply to the website as a whole, including everything written
+The following conventions apply to the website as a whole, including everything
-in HTML, CSS, YAML, and Liquid. These conventions are intended to keep the
+written in HTML, CSS, YAML, and Liquid. These conventions are intended to keep
-codebase consistent when multiple collaborators are working on it. They should
+the codebase consistent when multiple collaborators are working on it. They
-be understood as a practical set of rules for maintaining order in this
+should be understood as a practical set of rules for maintaining order in this
 specific codebase rather than as a statement of what is objectively right or
 good.
 
-* Always use spaces. Never use tabs.
+### General practices
-* Indent by exactly two (2) spaces.
+
-* Whenever you add an opening tag, indent the following line. (Exception: If
+- Use comments to indicate the purposes of different blocks of code. This makes
-  you open and close the tag on the same line, do not indent the following
-  line.)
-* Indent Liquid the same way as HTML.
-* In general, the starting columns of every adjacent pair of lines should be no
-  more than two spaces apart (example below).
-* No blank or empty lines. (Hint: When you feel you need one, add a comment on
-  that line instead.)
-* Use comments to indicate the purposes of different blocks of code. This makes
   the file easier to understand and navigate.
-* Use descriptive variable names. Never use one or two letter variable names.
+
-  Avoid uncommon abbreviations and made-up words.
+- Use descriptive variable names. Never use one or two letter variable names.
-* In general, make it easy for others to read your code. Your future self will
+  Avoid obscure abbreviations and made-up words.
+
+- In general, make it easy for others to read your code. Your future self will
   thank you, and so will your collaborators!
-* [Don't Repeat Yourself
+
+- [Don't Repeat Yourself
   (DRY)!](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) Instead of
   repeating the same block of code multiple times, abstract it out into a
   separate file and `include` that file where you need it.
 
-### Indentation example
+### Whitespace
+
+- Always use spaces. Never use tabs.
+
+- Each indentation step should be exactly two (2) spaces.
+
+- Whenever you add an opening tag, indent the following line. (Exception: If
+  you open and close the tag on the same line, do not indent the following
+  line.)
+
+- Indent Liquid the same way as HTML.
+
+- In general, the starting columns of every adjacent pair of lines should be no
+  more than two spaces apart (example below).
+
+- No blank or empty lines. (Hint: When you feel you need one, add a comment on
+  that line instead.)
+
+#### Indentation example
 
 Here's an example that follows the indentation rules: