Reorganize doc guidelines into multiple pages; update style guide

The existing doc guidelines page attempts to combine too many different
topics at once and includes information that does not pertain directly
to the documentation. This reorganization is intended to make each type
of information easier to find. For example, some have found it difficult
to find the documentation style guidelines (see, e.g.,
QubesOS/qubes-issues#6701#issuecomment-875875610). This reorganization
allows us to assign more specific titles to each page.

General changes:
- Create new page for contribution instructions
- Create new page for website style guide
- Create new page for continuous integration
- Rename existing "style guide" to "visual style guide" in order to
  avoid ambiguity with new doc and website style guides
- Retain existing page solely for doc style guide
- Update page names and permalinks
- Update existing links
- Improve language

Doc style guide changes:
- Add section on using sentence case in headings
  (see QubesOS/qubes-issues#6756 and #1173)
- Improve section organization
- Clarify language

In order to better preserve the Git history of each file, file renames
will be handled in a separate commit.
This commit is contained in:
Andrew David Wong 2021-07-08 07:41:19 -07:00
parent c4f59952f5
commit c29cf40910
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
15 changed files with 481 additions and 411 deletions

View file

@ -24,7 +24,7 @@ ways in which you can help:
* Record [video tours](/video-tours/)
* Create [artwork](https://github.com/QubesOS/qubes-artwork) (plymouth themes,
installer themes, wallpapers, etc.)
* [Write and edit the documentation](/doc/doc-guidelines)
* [Write and edit the documentation](/doc/how-to-edit-the-documentation)
* [Donate](/donate/) to the project
* If you represent an organization, become a [Qubes partner](/partners/)
* Add a [Qubes download mirror](/downloads/mirrors/)

View file

@ -267,7 +267,9 @@ Please see the coreboot website / their IRC channel for further information.
### How should I report documentation issues?
Please see the [documentation guidelines](/doc/doc-guidelines).
If you can fix the problem yourself, please see [how to edit the
documentation](/doc/how-to-edit-the-documentation). If not, please see [issue
tracking](/doc/issue-tracking).
### Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
@ -279,7 +281,7 @@ This website is hosted on [GitHub Pages](https://pages.github.com/) ([why?](#why
Therefore, it is largely outside of our control.
We don't consider this a problem, however, since we explicitly [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure).
For this reason, we don't think that anyone should place undue trust in the live version of this site on the Web.
Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing) (which indicates that the content has undergone review per our [documentation guidelines](/doc/doc-guidelines)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/doc-guidelines/#markdown-conventions).
Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing) (which indicates that the content has undergone [review](/doc/how-to-edit-the-documentation/#security)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/documentation-style-guide/#markdown-conventions).
We've gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
### What does it mean to "distrust the infrastructure"?

View file

@ -249,4 +249,4 @@ GitHub](https://github.com/QubesOS).
## Documentation
Peruse our extensive library of [documentation](/doc/) for users and developers
of Qubes OS. You can even [help us improve it](/doc/doc-guidelines/)!
of Qubes OS. You can even [help us improve it](/doc/how-to-edit-the-documentation/)!

View file

@ -34,9 +34,9 @@ Support, Mailing Lists, and Forum](/support/).
### I see something that should be changed in the documentation.
We encourage you to submit the change yourself! Please see the [Documentation
Guidelines](/doc/doc-guidelines/) for instructions on how to do so. If it's
something you can't do yourself, please proceed to open an issue.
We encourage you to submit the change yourself! Please see the [how to edit the
documentation](/doc/how-to-edit-the-documentation/) for instructions on how to
do so. If it's something you can't do yourself, please proceed to open an issue.
### I would like to report a security vulnerability.
@ -352,12 +352,3 @@ which means, "The fix has been released for the testing release but is pending
backport to the stable release." Our infrastructure will attempt to apply this
label automatically, when appropriate, but it is not perfect, and the
developers may be need to adjust it manually.
## See also
- [Help, Support, Mailing Lists, and Forum](/support/)
- [Testing New Releases and Updates](/doc/testing/)
- [How to Contribute](/doc/contributing/)
- [Contributing Code](/doc/contributing/#contributing-code)
- [Package Contributions](/doc/package-contributions/)
- [Documentation Guidelines](/doc/doc-guidelines/)

View file

@ -124,7 +124,7 @@ contributions](/doc/code-signing/).
For example, you might find it easier to trust advice from someone who has a
proven track record of [contributing software
packages](/doc/package-contributions/) or [contributing to the
documentation](/doc/doc-guidelines/). It's unlikely that individuals who have
documentation](/doc/how-to-edit-the-documentation/). It's unlikely that individuals who have
worked hard to build good reputations for themselves through their
contributions over the years would risk giving malicious advice in signed
messages to public mailing lists. Since every contribution to the Qubes OS
@ -217,7 +217,7 @@ not a discussion
forum](/doc/issue-tracking/#the-issue-tracker-is-not-a-discussion-forum).)
Likewise, if you see that something in the documentation should be changed,
don't simply point it out in a discussion venue. Instead, [submit the
change](/doc/doc-guidelines/).
change](/doc/how-to-edit-the-documentation/).
### Moderation