qubes-doc/basics_user/doc-guidelines.md

layout	title	permalink	redirect_from
doc	Documentation Guidelines	/doc/doc-guidelines/	/en/doc/doc-guidelines/ /wiki/DocStyle/ /doc/DocStyle/

Documentation Guidelines

All Qubes OS documentation pages are stored as plain text files in the dedicated 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 everything accurate and comprehensive. If you notice a problem with the documentation or some way it can be improved, please report it! Better yet, you can edit the documentation yourself, both to add or improve existing content.

How to Report Issues

To report an issue, please create one in qubes-issues, but before you do, please make sure it does not already exist. Documentation-related issues will be assigned the doc label. Issues which have been created in qubes-issues are significantly more likely to be addressed than those sent in emails to the mailing lists or to individuals.

How to Contribute

Editing the documentation is easy, so if you spot any errors, please help us fix them! (As mentioned above, the documentation maintainers are just volunteers who have day jobs of their own, so we rely heavily on the community to improve the documentation.) Since Qubes is a security-oriented project, every documentation change will be reviewed before it's published to the web. This allows us to maintain quality control and protect our users.

As mentioned above, we keep all the documentation in a dedicated Git repository hosted on GitHub. Thanks to GitHub's interface, you can edit the 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 command line, you can skip the rest of this section. All you need to do to contribute is to fork and clone the qubes-doc repo, make your changes, then submit a pull request.)

Ok, let's start. Every documentation page has an "Edit this page" button. It may be on the right side (in the desktop layout):

Or at the bottom (in the mobile layout):

When you click on it, you'll be prompted for your GitHub username and password (if you aren't already logged in). You can also create an account from here.

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.

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.

Once you're finished, describe your changes at the bottom and click "Propose file change".

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.

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.

That's all! We will review your changes. If everything looks good, we'll pull them into the official documentation. Otherwise, we may have some questions for 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.

Version-specific Documentation

We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each version of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all current, stable releases of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage. 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.

Contribution Suggestions

• If you find any inaccuracies in the documentation, please correct them!

• If you find an inaccuracy but don't know how to correct it, you can still help by documenting the inaccuracy. For example, if you have thoroughly tested a set of steps in the documentation and know for certain that they no longer work on a certain version of Qubes (maybe because the steps are out-of-date), then please add a note to the documentation indicating this. You may also wish to provide a link to a relevant thread on the mailing lists.

• Where appropriate, specify the version of the software to which your contribution applies. For example, if you're contributing a set of instructions for doing something in dom0, specify the version(s) of Qubes OS with which you know these instructions to work. This allows future readers to more easily estimate the accuracy and applicability of information.

Style Guidelines

• Familiarize yourself with the terms defined in the glossary. Use these terms consistently and accurately throughout your writing.

Markdown Conventions

All the documentation is written in Markdown for maximum accessibility. When making contributions, please try to observe the following style conventions:

• Use spaces instead of tabs.
• In order to enable offline browsing, use relative paths (e.g., /doc/doc-guidelines/ instead of https://www.qubes-os.org/doc/doc-guidelines/, except when the source text will be reproduced outside of the Qubes website repo. Examples of exceptions:
  • QSBs (intended to be read as plain text)
  • News posts (plain text is reproduced on the mailing lists)
  • URLs that appear inside code blocks (e.g., in comments and document templates)
  • Files like README.md and CONTRIBUTING.md
• Insert a newline at the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples).
  • Rationale: This practice is most appropriate for source that consists primarily of natural language text. It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability.
• 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.
• Use hanging indentations
  where appropriate.
• Use underline headings (===== and -----) if possible. If this is not possible, use Atx-style headings on both the left and right sides (### H3 ###).
• Use [reference-style][ref] links.

[ref]: https://daringfireball.net/projects/markdown/syntax#link

(This is a great source for learning about Markdown.)

Git Conventions

Please try to write good commit messages, according to the instructions in our coding style guidelines.