Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-26 06:26:18 -05:00
Code Issues Packages Projects Releases Wiki Activity

Revert "Fix image example; wrap text"

Browse Source 
This reverts commit 7d7ca0c5924f17a435ee21f17bfa8b3266995e19.
This commit is contained in:
Andrew David Wong 2021-06-18 05:39:28 -07:00
parent 7d7ca0c592
commit 863f0ee9bd
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 158 additions and 298 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

456
developer/general/doc-guidelines.md
View File

@ -10,88 +10,56 @@ ref: 30
title: Documentation Guidelines title: Documentation Guidelines
--- ---
All Qubes OS documentation pages are stored as plain text files in the
dedicated [qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By
cloning and regularly pulling from this repo, users can maintain their own
up-to-date offline copy of all Qubes documentation rather than relying solely
on the web.
The documentation is a community effort. Volunteers work hard trying to keep All Qubes OS documentation pages are stored as plain text files in the dedicated [qubes-doc](https://github.com/QubesOS/qubes-doc) repository.
everything accurate and comprehensive. If you notice a problem or some way it By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
can be improved, please [edit the documentation](#how-to-contribute)!
The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive.
If you notice a problem or some way it can be improved, please [edit the documentation](#how-to-contribute)!
## Security ## Security
*Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)* *Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)*
All pull requests (PRs) against All pull requests (PRs) against [qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be merged, except in the case of [external documentation](/doc/#external-documentation) (see [#4693](https://github.com/QubesOS/qubes-issues/issues/4693)).
[qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be This process is designed to ensure that contributed text is accurate and non-malicious.
merged, except in the case of [external This process is a best effort that should provide a reasonable degree of assurance, but it is not foolproof.
documentation](/doc/#external-documentation) (see For example, all text characters are checked for ANSI escape sequences.
[#4693](https://github.com/QubesOS/qubes-issues/issues/4693)). This process is However, binaries, such as images, are simply checked to ensure they appear or function the way they should when the website is rendered.
designed to ensure that contributed text is accurate and non-malicious. This They are not further analyzed in an attempt to determine whether they are malicious.
process is a best effort that should provide a reasonable degree of assurance,
but it is not foolproof. For example, all text characters are checked for ANSI
escape sequences. However, binaries, such as images, are simply checked to
ensure they appear or function the way they should when the website is
rendered. They are not further analyzed in an attempt to determine whether they
are malicious.
Once a pull request passes review, the reviewer should add a signed comment Once a pull request passes review, the reviewer should add a signed comment stating, "Passed review as of `<latest_commit>`" (or similar).
stating, "Passed review as of `<latest_commit>`" (or similar). The The documentation maintainer then verifies that the pull request is mechanically sound (no merge conflicts, broken links, ANSI escapes, etc.).
documentation maintainer then verifies that the pull request is mechanically If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote.
sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
documentation maintainer then merges the pull request, adds a PGP-signed tag to
the latest commit (usually the merge commit), then pushes to the remote. In
cases in which another reviewer is not required, the documentation maintainer
may review the pull request (in which case no signed comment is necessary,
since it would be redundant with the signed tag).
## Questions, problems, and improvements ## Questions, problems, and improvements
If you have a question about something you read in the documentation, please If you have a question about something you read in the documentation, please send it to the appropriate [mailing list](/support/).
send it to the appropriate [mailing list](/support/). If you see that something If you see that something in the documentation should be fixed or improved, please [contribute](#how-to-contribute) the change yourself.
in the documentation should be fixed or improved, please To report an issue with the documentation, please follow our standard [issue reporting guidelines](/doc/reporting-bugs/).
[contribute](#how-to-contribute) the change yourself. To report an issue with (If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
the documentation, please follow our standard [issue reporting
guidelines](/doc/reporting-bugs/). (If you report an issue with the
documentation, you will likely be asked to address it, unless there is a clear
indication in your report that you are not willing or able to do so.)
## How to contribute ## How to contribute
Editing the documentation is easy, so if you see that a change should be made, Editing the documentation is easy, so if you see that a change should be made, please contribute it!
please contribute it!
A few notes before we get started: 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.
be reviewed before it's accepted. This allows us to maintain quality control This allows us to maintain quality control and protect our users.
and protect our users. * We don't want you to spend time and effort on a contribution that we can't accept.
* We don't want you to spend time and effort on a contribution that we can't If your contribution would take a lot of time, please [file an issue](/doc/reporting-bugs/) for it first so that we can make sure we're on the same page before significant works begins.
accept. If your contribution would take a lot of time, please [file an * 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.
issue](/doc/reporting-bugs/) for it first so that we can make sure we're on In this case, you can still submit it by following the instructions below.
the same page before significant works begins. 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.
* 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.
As mentioned above, we keep all the documentation in a dedicated [Git 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/).
repository](https://github.com/QubesOS/qubes-doc) hosted on Thanks to GitHub's interface, you can edit the documentation even if you don't know Git at all!
[GitHub](https://github.com/). Thanks to GitHub's interface, you can edit the The only thing you need is a GitHub account, which is free.
documentation even if you don't know Git at all! The only thing you need is a
GitHub account, which is free.
(**Note:** If you're already familiar with GitHub or wish to work from the (**Note:** If you're already familiar with GitHub or wish to work from the command line, you can skip the rest of this section.
command line, you can skip the rest of this section. All you need to do to All you need to do to contribute is to [fork and clone](https://guides.github.com/activities/forking/) the [qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests/).)
contribute is to [fork and
clone](https://guides.github.com/activities/forking/) the
[qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then
[submit a pull
request](https://help.github.com/articles/using-pull-requests/).)
Ok, let's start. Ok, let's start.
Every documentation page has an "Edit this page" button. Every documentation page has an "Edit this page" button.
@ -103,191 +71,129 @@ Or at the bottom (in the mobile layout):
[![edit-button-mobile](/attachment/doc/02-button1.png) [![edit-button-mobile](/attachment/doc/02-button1.png)
When you click on it, you'll be prompted for your GitHub username and password When you click on it, you'll be prompted for your GitHub username and password (if you aren't already logged in).
(if you aren't already logged in). You can also create an account from here. You can also create an account from here.
[![github-sign-in](/attachment/doc/04-sign-in.png) [![github-sign-in](/attachment/doc/04-sign-in.png)
If this is your first contribution to the documentation, you need to "fork" the 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.
repository (make your own copy). It's easy --- just click the big green button This step is only needed the first time you make a contribution.
on the next page. This step is only needed the first time you make a
contribution.
[![fork](/attachment/doc/05-fork.png) [![fork](/attachment/doc/05-fork.png)
Now you can make your modifications. You can also preview the changes to see Now you can make your modifications.
how they'll be formatted by clicking the "Preview changes" tab. If you want to You can also preview the changes to see how they'll be formatted by clicking the "Preview changes" tab.
add images, please see [How to add images](#how-to-add-images). If you're If you want to add images, please see [How to add images](#how-to-add-images).
making formatting changes, please [render the site If you're 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.
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) [![edit](/attachment/doc/06-edit.png)
Once you're finished, describe your changes at the bottom and click "Propose Once you're finished, describe your changes at the bottom and click "Propose file change".
file change".
[![commit](/attachment/doc/07-commit-msg.png) [![commit](/attachment/doc/07-commit-msg.png)
After that, you'll see exactly what modifications you've made. At this stage, After that, you'll see exactly what modifications you've made.
those changes are still in your own copy of the documentation ("fork"). If At this stage, those changes are still in your own copy of the documentation ("fork").
everything looks good, send those changes to us by pressing the "Create pull If everything looks good, send those changes to us by pressing the "Create pull request" button.
request" button.
[![pull-request](/attachment/doc/08-review-changes.png) [![pull-request](/attachment/doc/08-review-changes.png)
You will be able to adjust the pull request message and title there. In most You will be able to adjust the pull request message and title there.
cases, the defaults are ok, so you can just confirm by pressing the "Create In most cases, the defaults are ok, so you can just confirm by pressing the "Create pull request" button again.
pull request" button again.
[![pull-request-confirm](/attachment/doc/09-create-pull-request.png) [![pull-request-confirm](/attachment/doc/09-create-pull-request.png)
If any of your changes should be reflected in the [documentation index (a.k.a. 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, changing the title of an existing page, or removing a page --- please see [How to edit the documentation index](#how-to-edit-the-documentation-index).
table of contents)](/doc/) --- for example, if you're adding a new page,
changing the title of an existing page, or removing a page --- please see [How
to edit the documentation index](#how-to-edit-the-documentation-index).
That's all! We will review your changes. If everything looks good, we'll pull That's all!
them into the official documentation. Otherwise, we may have some questions for We will review your changes.
you, which we'll post in a comment on your pull request. (GitHub will If everything looks good, we'll pull them into the official documentation.
automatically notify you if we do.) If, for some reason, we can't accept your Otherwise, we may have some questions for you, which we'll post in a comment on your pull request.
pull request, we'll post a comment explaining why we can't. (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) [![done](/attachment/doc/10-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/) The source file for the [documentation index (a.k.a. table of contents)](/doc/) lives here:
lives here:
<https://github.com/QubesOS/qubesos.github.io/blob/master/_data/index.yml> <https://github.com/QubesOS/qubesos.github.io/blob/master/_data/index.yml>
Editing this file will change what appears on the documentation index. If your Editing this file will change what appears on the documentation index.
pull request (PR) adds, removes, or edits anything that should be reflected in If your 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.
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 To add an image to a page, use the following syntax in the main document.
will make the image a hyperlink to the image file, allowing the reader to click This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the image by itself.
on the image in order to view the image by itself.
``` ```
[![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png) [![Image Title](/attachment/doc/image-filename.png)
``` ```
Then, submit your image(s) in a separate pull request to the Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename.
[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository This is the only permitted way to include images.
using the same path and filename. This is the only permitted way to include Do not link to images on other websites.
images. Do not link to images on other websites.
## Organizational guidelines ## Organizational guidelines
### Do not duplicate documentation ### Do not duplicate documentation
Duplicating documentation is almost always a bad idea. There are many reasons Duplicating documentation is almost always a bad idea.
for this. The main one is that almost all documentation has to be updated as There are many reasons for this.
some point. When similar documentation appears in more than one place, it is The main one is that almost all documentation has to be updated as some point.
very easy for it to get updated in one place but not the others (perhaps When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn't realize it's in more than once place).
because the person updating it doesn't realize it's in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users.
When this happens, the documentation as a whole is now inconsistent, and the Such traps are often more harmful than if the documentation never existed in the first place.
outdated documentation becomes a trap, especially for novice users. Such traps The solution is to **link** to existing documentation rather than duplicating it.
are often more harmful than if the documentation never existed in the first There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare.
place. The solution is to **link** to existing documentation rather than
duplicating it. There are some exceptions to this policy (e.g., information
that is certain not to change for a very long time), but they are rare.
### Core vs. external documentation ### Core vs. external documentation
Core documentation resides in the [Qubes OS Project's official Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc).
repositories](https://github.com/QubesOS/), mainly in External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Community](https://github.com/Qubes-Community) project.
[qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc).
be anywhere else (such as forums, community websites, and blogs), but there is If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Community](https://github.com/Qubes-Community) project instead.
an especially large collection in the [Qubes However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine.
Community](https://github.com/Qubes-Community) project. External documentation Indeed, the maintainers of the [Qubes Community](https://github.com/Qubes-Community) project should regularly submit PRs against the documentation index (see [How to edit the documentation index](#how-to-edit-the-documentation-index)) to add and update Qubes Community links in the "External Documentation" section of the documentation table of contents.
should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc).
If you've written a piece of documentation that is not appropriate for
[qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit
it to the [Qubes Community](https://github.com/Qubes-Community) project
instead. However, *linking* to external documentation from
[qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed,
the maintainers of the [Qubes Community](https://github.com/Qubes-Community)
project should regularly submit PRs against the documentation index (see [How
to edit the documentation index](#how-to-edit-the-documentation-index)) to add
and update Qubes Community links in the "External Documentation" section of the
documentation table of contents.
The main difference between **core** (or **official**) and **external** (or The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project.
**community** or **unofficial**) documentation is whether it documents software The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project.
that is officially written and maintained by the Qubes OS Project. The purpose In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else.
of this distinction is to keep the core docs maintainable and high-quality by For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/).
limiting them to the software output by the Qubes OS Project. In other words, However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own.
we take responsibility for documenting all of the software we put out into the This is particularly true when it comes to Linux in general.
world, but it doesn't make sense for us to take on the responsibility of Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.
documenting or maintaining documentation for anything else. For example, Qubes
OS may use a popular Linux distribution for an official
[TemplateVM](/doc/templates/). However, it would not make sense for a
comparatively small project like ours, with modest funding and a lean
workforce, to attempt to document software belonging to a large, richly-funded
project with an army of paid and volunteer contributors, especially when they
probably already have documentation of their own. This is particularly true
when it comes to Linux in general. Although many users who are new to Qubes are
also new to Linux, it makes absolutely no sense for our comparatively tiny
project to try to document Linux in general when there is already a plethora of
documentation out there.
Many contributors do not realize that there is a significant amount of work Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written.
involved in *maintaining* documentation after it has been written. They may They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward.
wish to write documentation and submit it to the core docs, but they see only Submissions to the core docs also have to go through a review process to ensure accuracy before being merged (see [security](#security)), which takes up valuable time from the team.
their own writing process and fail to consider that it will have to be kept We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time.
up-to-date and consistent with the rest of the docs for years afterward. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes.
Submissions to the core docs also have to go through a review process to ensure It's also important to periodically review and update this documentation, especially when a new Qubes release comes out.
accuracy before being merged (see [security](#security)), which takes up Periodically, there may be technical or policy changes that affect all the core documentation.
valuable time from the team. We aim to maintain high quality standards for the The more documentation there is relative to maintainers, the harder all of this will be.
core docs (style and mechanics, formatting), which also takes up a lot of time. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.
If the documentation involves anything external to the Qubes OS Project (such
as a website, platform, program, protocol, framework, practice, or even a
reference to a version number), the documentation is likely to become outdated
when that external thing changes. It's also important to periodically review
and update this documentation, especially when a new Qubes release comes out.
Periodically, there may be technical or policy changes that affect all the core
documentation. The more documentation there is relative to maintainers, the
harder all of this will be. Since there are many more people who are willing to
write documentation than to maintain it, these individually small incremental
additions amount to a significant maintenance burden for the project.
On the positive side, we consider the existence of community documentation to On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world.
be a sign of a healthy ecosystem, and this is quite common in the software The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes.
world. The community is better positioned to write and maintain documentation In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as `qrexec`, it does not make sense to include every tutorial that says "here's how to do something cool with `qrexec`" in the core docs.
that applies, combines, and simplifies the official documentation, e.g., Such tutorials generally also belong in the community documentation.
tutorials that explain how to install and use various programs in Qubes, how to
create custom VM setups, and introductory tutorials that teach basic Linux
concepts and commands in the context of Qubes. In addition, just because the
Qubes OS Project has officially written and maintains some flexible framework,
such as `qrexec`, it does not make sense to include every tutorial that says
"here's how to do something cool with `qrexec`" in the core docs. Such
tutorials generally also belong in the community documentation.
See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more background information.
background information.
### Version-specific documentation ### Version-specific documentation
*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential *See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential changes to this policy.*
changes to this policy.*
We maintain only one set of documentation for Qubes OS. We do not maintain a We maintain only one set of documentation for Qubes OS.
different set of documentation for each version of Qubes. Our single set of We do not maintain a different set of documentation for each version of Qubes.
Qubes OS documentation is updated on a continual, rolling basis. Our first Our single set of Qubes OS documentation is updated on a continual, rolling basis.
priority is to document all **current, stable releases** of Qubes. Our second Our first priority is to document all **current, stable releases** of Qubes.
priority is to document the next, upcoming release (if any) that is currently Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.
in the beta or release candidate stage.
In cases where a documentation page covers functionality that differs In cases where a documentation page covers functionality that differs considerably between Qubes OS versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions:
considerably between Qubes OS versions, the page should be subdivided into
clearly-labeled sections that cover the different functionality in different
versions:
#### Incorrect Example #### Incorrect Example
@ -350,69 +256,42 @@ general `qubes-baz` command:
Once you foo, make sure to close the baz before fooing the next bar. 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 Subdividing the page into clearly-labeled sections for each version has several benefits:
benefits:
* It preserves good content for older (but still supported) versions. Many * It preserves good content for older (but still supported) versions.
documentation contributors are also people who prefer to use the latest Many documentation contributors are also people who prefer to use the latest version.
version. Many of them are tempted to *replace* existing content that applies Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version.
to an older, supported version with content that applies only to the latest This is somewhat understandable.
version. This is somewhat understandable. Since they only use the latest Since they only use the latest version, they may be focused on their own experience, and they may even regard the older version as deprecated, even when it's actually still supported.
version, they may be focused on their own experience, and they may even However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported version.
regard the older version as deprecated, even when it's actually still In many cases, these users value the stability and reliability of the older, supported version.
supported. However, allowing this replacement of content would do a great With the older, supported version, there has been more time to fix bugs and make improvements in both the software and the documentation.
disservice to those who still rely on the older, supported version. In many Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision.
cases, these users value the stability and reliability of the older, 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.
supported version. With the older, supported version, there has been more * 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.
time to fix bugs and make improvements in both the software and the * It's hard for readers to miss information they need, since it's all in one place.
documentation. Consequently, much of the documentation content for this 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.
version may have gone through several rounds of editing, review, and In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored.
revision. It would be a tragedy for this content to vanish while the very set The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice.
of users who most prize stability and reliability are depending on it. Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated.
* It's easy for readers to quickly find the information they're looking for, Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing:
since they can go directly to the section that applies to their version. We want the 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 hard for readers to miss information they need, since it's all in one * 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.
place. In the incorrect example, information that the reader needs could be 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 this treatment, since they apply to all currently-supported Qubes OS versions.
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
the headings in order to know which parts of the page need to be read and
which can be safely ignored. The fact that some content is repeated in the
two version-specific sections is not a problem, since no reader has to read
the same thing twice. Moreover, as one version gets updated, it's likely that
the documentation for that version will also be updated. Therefore, content
that is initially duplicated between version-specific sections will not
necessarily stay that way, and this is a good thing: We want the
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
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
this treatment, since they apply to all currently-supported Qubes OS
versions.
By contrast, an alternative approach, such as segregating the documentation By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so.
into two different branches, would mean that contributions that apply to both Most of the time, this wouldn't happen.
Qubes versions would only end up in one branch, unless someone remembered to When it did, it would mean a second pull request that would have to be reviewed.
manually submit the same thing to the other branch and actually made the effort Over time, the different branches would diverge in non-version-specific content.
to do so. Most of the time, this wouldn't happen. When it did, it would mean a Good general content that was submitted only to one branch would effectively disappear once that version was deprecated.
second pull request that would have to be reviewed. Over time, the different (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated version, and there would be a motivation to remove it from the website so that search results wouldn't be populated with out-of-date information.)
branches would diverge in non-version-specific content. Good general content
that was submitted only to one branch would effectively disappear once that
version was deprecated. (Even if it were still on the website, no one would
look at it, since it would explicitly be in the subdirectory of a deprecated
version, and there would be a motivation to remove it from the website so that
search results wouldn't be populated with out-of-date information.)
For further discussion about version-specific documentation in Qubes, see For further discussion about version-specific documentation in Qubes, see [here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
## Style guidelines ## Style guidelines
* Familiarize yourself with the terms defined in the * Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). Use these
[glossary](/doc/glossary/). Use these terms consistently and accurately terms consistently and accurately throughout your writing.
throughout your writing.
* Syntactically distinguish variables in commands. * Syntactically distinguish variables in commands.
For example, this is ambiguous: For example, this is ambiguous:
@ -429,46 +308,30 @@ For further discussion about version-specific documentation in Qubes, see
## Markdown conventions ## Markdown conventions
All the documentation is written in Markdown for maximum accessibility. When All the documentation is written in Markdown for maximum accessibility.
making contributions, please try to observe the following style conventions: When making contributions, please try to observe the following style conventions:
* Use spaces instead of tabs. * Use spaces instead of tabs.
* Do not write HTML inside Markdown documents (except in rare, unavoidable * Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as alerts).
cases, such as alerts). In particular, never include HTML or CSS for In particular, never include HTML or CSS for styling, formatting, or white space control.
styling, formatting, or white space control. That belongs in the (S)CSS That belongs in the (S)CSS files instead.
files instead. * Link only to images in [qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see [instructions above](#how-to-add-images)).
* Link only to images in Do not link to images on other websites.
[qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see * In order to enable offline browsing and automatic onion redirection, always use relative (rather than absolute) links, e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`.
[instructions above](#how-to-add-images)). Do not link to images on other Examples of exceptions:
websites. * The signed plain text portions of [QSBs](/security/bulletins/) and [Canaries](/security/canaries/)
* In order to enable offline browsing and automatic onion redirection, always * URLs that appear inside code blocks (e.g., in comments and document templates)
use relative (rather than absolute) links, e.g., `/doc/doc-guidelines/`
instead of `https://www.qubes-os.org/doc/doc-guidelines/`. Examples of
exceptions:
* The signed plain text portions of [QSBs](/security/bulletins/) and
[Canaries](/security/canaries/)
* URLs that appear inside code blocks (e.g., in comments and document
templates)
* Files like `README.md` and `CONTRIBUTING.md` * Files like `README.md` and `CONTRIBUTING.md`
* Hard wrap Markdown lines at 80 characters, unless the line can't be broken * Hard wrap Markdown lines at 80 characters, unless the line can't be broken (e.g., code or a URL).
(e.g., code or a URL). * If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
* If appropriate, make numerals in numbered lists match between Markdown * 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.
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.
* Use hanging indentations * Use hanging indentations
where appropriate. where appropriate.
* Do not use `h1` headings (single `#` or `======` underline). These are * Do not use `h1` headings (single `#` or `======` underline). These are automatically generated from the `title:` line in the YAML frontmatter.
automatically generated from the `title:` line in the YAML frontmatter.
* Use Atx-style headings: , `##h 2`, `### h3`, etc. * Use Atx-style headings: , `##h 2`, `### h3`, etc.
* When writing code blocks, use [syntax * 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.
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: * When providing command line examples:
* Tell the reader where to open a terminal (dom0 or a specific domU), and * 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.:
show the command along with its output (if any) in a code block, e.g.:
~~~markdown ~~~markdown
Open a terminal in dom0 and run: Open a terminal in dom0 and run:
@ -479,9 +342,8 @@ 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:
prompt should contain a trailing `#` (for the user `root`) or `$` (for At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
other users) on Linux systems and `>` on Windows systems, respectively.
* Don't try to add comments inside the code block. * Don't try to add comments inside the code block.
For example, *don't* do this: For example, *don't* do this:
@ -498,15 +360,13 @@ making contributions, please try to observe the following style conventions:
The `#` symbol preceding each comment is ambiguous with a root command prompt. The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose. Instead, put your comments *outside* of the code block in normal prose.
* Use non-reference-style links like `[website](https://example.com/)`. Do * Use non-reference-style links like `[website](https://example.com/)`.
*not* use reference links like `[website][example]`, `[website][]` or Do *not* use reference links like `[website][example]`, `[website][]` or `[website]`.
`[website]`.
([This](https://daringfireball.net/projects/markdown/) is a great source for ([This](https://daringfireball.net/projects/markdown/) is a great source for learning about Markdown.)
learning about Markdown.)
## Git conventions ## Git conventions
Please try to write good commit messages, according to the [instructions in our Please try to write good commit messages, according to the
coding style guidelines](/doc/coding-style/#commit-message-guidelines). [instructions in our coding style guidelines](/doc/coding-style/#commit-message-guidelines).