mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-10-01 01:25:40 -04:00
182 lines
7.2 KiB
Markdown
182 lines
7.2 KiB
Markdown
---
|
|
layout: doc
|
|
title: Documentation Guidelines
|
|
permalink: /doc/doc-guidelines/
|
|
redirect_from:
|
|
- /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][contribute] 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][qubes-doc] hosted on [GitHub]. Thanks to GitHub 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][gh-fork] the [qubes-doc] repo, make your changes, then
|
|
[submit a pull request][gh-pull].)
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
* Insert a newline at the end of each sentence.
|
|
* 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][md] 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][git-commit].
|
|
|
|
|
|
[qubes-doc]: https://github.com/QubesOS/qubes-doc
|
|
[glossary]: /doc/glossary/
|
|
[report]: #how-to-report-issues
|
|
[contribute]: #how-to-contribute
|
|
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
|
|
[gh-fork]: https://guides.github.com/activities/forking/
|
|
[gh-pull]: https://help.github.com/articles/using-pull-requests/
|
|
[GitHub]: https://github.com/
|
|
[mailing lists]: /mailing-lists/
|
|
[md]: https://daringfireball.net/projects/markdown/
|
|
[git-commit]: /doc/coding-style/#commit-message-guidelines
|