2015-09-22 06:31:53 -04:00
|
|
|
---
|
|
|
|
|
layout: doc
|
|
|
|
|
title: Documentation Guidelines
|
2015-10-28 18:14:40 -04:00
|
|
|
permalink: /doc/doc-guidelines/
|
2015-09-22 06:31:53 -04:00
|
|
|
redirect_from:
|
2015-10-28 18:14:40 -04:00
|
|
|
- /en/doc/doc-guidelines/
|
|
|
|
|
- /wiki/DocStyle/
|
|
|
|
|
- /doc/DocStyle/
|
2015-09-22 06:31:53 -04:00
|
|
|
---
|
|
|
|
|
|
|
|
|
|
Guidelines for Documentation Contributors
|
|
|
|
|
=========================================
|
|
|
|
|
|
|
|
|
|
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. Contributions to the
|
|
|
|
|
documentation (both new content and edits of existing content) are welcome. To
|
|
|
|
|
contribute, please [fork and clone][gh-fork] this repo, make your changes,
|
|
|
|
|
then either [submit a pull request][gh-pull] or [send a patch][patch] to the
|
|
|
|
|
`qubes-devel` [mailing list][lists]. If you have a GitHub account (free), you
|
|
|
|
|
can simply browse the [qubes-doc] repository and edit the files there. The
|
|
|
|
|
GitHub interface will automatically guide you through the
|
|
|
|
|
[fork and pull request creation process][gh-fork].
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Markdown Conventions
|
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
|
|
All the documentation is written in Markdown for maximum accessibility. When
|
|
|
|
|
making contributions, please observe the following style conventions:
|
|
|
|
|
|
|
|
|
|
* Use spaces instead of tabs.
|
|
|
|
|
* Hard wrap Markdown lines at 80 characters.
|
|
|
|
|
* Hard wrap Git commit message lines at 72 characters.
|
|
|
|
|
* This leaves exactly four spaces on each side of the commit message when
|
|
|
|
|
viewed in the default `git log` format.)
|
|
|
|
|
* If appropriate, make numerals in numbered lists match between Markdown
|
|
|
|
|
source and HTML output.
|
|
|
|
|
* 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]: http://daringfireball.net/projects/markdown/syntax#link`
|
|
|
|
|
|
2016-01-29 07:40:00 -05:00
|
|
|
Editing Qubes documentation
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
Editing Qubes documentation is easy, if you spot some errors, feel free to
|
|
|
|
|
correct it. Because Qubes OS is security-oriented project, every documentation
|
|
|
|
|
change will be reviewed before being visible on the main page.
|
|
|
|
|
|
|
|
|
|
First of all, we keep documentation in git repository hosted on
|
|
|
|
|
[github][github]. Thanks to github interface, you can edit documentation even
|
|
|
|
|
if you do not know git at all. But you need a github account for that (it is
|
|
|
|
|
free!).
|
|
|
|
|
|
|
|
|
|
Ok, lets start. Every documentation page have "Edit this page" button. It can
|
|
|
|
|
be on the right side (in desktop layout):
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Or at the bottom in mobile layout:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When you click on it, you'll be prompted for Github username and password (if
|
|
|
|
|
you aren't logged in already). You can also create an account from
|
|
|
|
|
there.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If it is your first contribution to the documentation, you need to "fork" a
|
|
|
|
|
repository (make your own copy). It's easy - just click that big green button
|
|
|
|
|
on the next page. This step is needed only for the first time.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Then you can make your modifications. You can also preview how the changes will
|
|
|
|
|
be formated using "Preview changes" tab above editor.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When you finish, describe your changes at the bottom and click "Propose file change".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
After that, you'll see what exactly modification you've made. At this stage
|
|
|
|
|
those changes are still in your own copy of the documentation ("fork"). If
|
|
|
|
|
everything is ok, send those change to us back using "Create pull request"
|
|
|
|
|
button.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You will be able to adjust pull request message and title there. In most cases
|
|
|
|
|
defaults are ok, so you can just confirm with "Create pull request" button
|
|
|
|
|
again.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
That's all! We will review your changes and eventually pull them into Qubes
|
|
|
|
|
documentation. You'll get email notification about that.
|
|
|
|
|
|
|
|
|
|
|
2015-09-22 06:31:53 -04:00
|
|
|
|
|
|
|
|
[qubes-doc]: https://github.com/QubesOS/qubes-doc
|
|
|
|
|
[qubes]: https://github.com/QubesOS
|
|
|
|
|
[gh-fork]: https://guides.github.com/activities/forking/
|
|
|
|
|
[gh-pull]: https://help.github.com/articles/using-pull-requests/
|
|
|
|
|
[patch]: /doc/SourceCode/#sending-a-patch
|
|
|
|
|
[lists]: https://www.qubes-os.org/doc/QubesLists/
|
2016-01-29 07:40:00 -05:00
|
|
|
[github]: https://github.com/
|
