Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update Documentation Guidelines

Browse Source 
* Update intro
* Add section on reporting issues
* Update links
* Prune old links
* Reorganize sections
This commit is contained in:
Axon 2016-03-14 13:47:07 +00:00
parent 8c9ca6ef5f
commit 3b9540f4a3
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 83 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
developers/doc-guidelines.md
View File

@ -14,82 +14,44 @@ Documentation Guidelines
All Qubes OS documentation pages are stored as plain text files in the All Qubes OS documentation pages are stored as plain text files in the
dedicated [qubes-doc] repository. By cloning and regularly pulling from 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 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 rather than relying solely on the Web.
documentation (both new content and edits of existing content) are welcome!
To contribute, please [fork and clone][gh-fork] this repo, make your changes, The documentation is a community effort in which volunteers work hard trying to
then either [submit a pull request][gh-pull] or [send a patch][patch] to the keep everything accurate and comprehensive. If you notice a problem with the
`qubes-devel` [mailing list][lists]. If you have a GitHub account (free), you documentation or some way it can be improved, please [report] it! Better
can simply browse the [qubes-doc] repository and edit the files there. The yet, you can [edit the documentation][contribute] yourself, both to add new
GitHub interface will automatically guide you through the content and to edit existing content.
[fork and pull request creation process][gh-fork]. (We provide a detailed
walkthrough of this process below.)
Style Guidelines How to Report Issues
----------------
* 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 To report an issue, please create an issue in [qubes-issues], but before you do,
making contributions, please try to observe the following style conventions: please make sure your issue does **not** already exist. Documentation-related
issues will be assigned the `doc` label. Issues which have been created in
* Use spaces instead of tabs. [qubes-issues] are significantly more likely to be addressed than those sent in
* Hard wrap Markdown lines at 80 characters. emails to the mailing lists or to individuals.
* 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 How to Contribute
--------------- -----------------
Please attempt to follow these conventions when writing your Git commit
messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions,
please see [this blog post][git-commit], which is the source of this list.
How to Contribute Using GitHub
------------------------------
Editing the documentation is easy, so if you spot any errors, please help us Editing the documentation is easy, so if you spot any errors, please help us
fix them! (The documentation maintainers are just volunteers who have day jobs fix them! (As mentioned above, the documentation maintainers are just volunteers
of their own, so we rely heavily on the community to improve the documentation.) who have day jobs of their own, so we rely heavily on the community to improve
Since Qubes is a security-oriented project, every documentation change will be the documentation.) Since Qubes is a security-oriented project, every
reviewed before it's published to the web. This allows us to maintain quality documentation change will be reviewed before it's published to the web. This
control and protect our users. allows us to maintain quality control and protect our users.
As mentioned above, we keep all the documentation in a dedicated Git repository As mentioned above, we keep all the documentation in a dedicated [Git
hosted on [GitHub][github]. Thanks to GitHub interface, you can edit the repository][qubes-doc] hosted on [GitHub]. Thanks to GitHub interface, you can
documentation even if you don't know Git at all! The only thing you need is a edit the documentation even if you don't know Git at all! The only thing you
GitHub account, which is free. 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 Ok, let's start. Every documentation page has an "Edit this page" button. It may
be on the right side (in the desktop layout): be on the right side (in the desktop layout):
@ -144,12 +106,62 @@ pull request, we'll post a comment explaining why we can't.
![done](/attachment/wiki/doc-edit/10-done.png) ![done](/attachment/wiki/doc-edit/10-done.png)
[md]: https://daringfireball.net/projects/markdown/ 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.
* Hard wrap Markdown lines at 80 characters.
* 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 attempt to follow these conventions when writing your Git commit
messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions,
please see [this blog post][git-commit], which is the source of this list.
[qubes-doc]: https://github.com/QubesOS/qubes-doc [qubes-doc]: https://github.com/QubesOS/qubes-doc
[qubes]: https://github.com/QubesOS [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-fork]: https://guides.github.com/activities/forking/
[gh-pull]: https://help.github.com/articles/using-pull-requests/ [gh-pull]: https://help.github.com/articles/using-pull-requests/
[patch]: /doc/SourceCode/#sending-a-patch [GitHub]: https://github.com/
[lists]: https://www.qubes-os.org/doc/QubesLists/ [md]: https://daringfireball.net/projects/markdown/
[github]: https://github.com/
[git-commit]: http://chris.beams.io/posts/git-commit/ [git-commit]: http://chris.beams.io/posts/git-commit/