From 3b9540f4a3d740a0889f8d2f8f5f5682cd4cedd4 Mon Sep 17 00:00:00 2001 From: Axon Date: Mon, 14 Mar 2016 13:47:07 +0000 Subject: [PATCH] Update Documentation Guidelines * Update intro * Add section on reporting issues * Update links * Prune old links * Reorganize sections --- developers/doc-guidelines.md | 154 +++++++++++++++++++---------------- 1 file changed, 83 insertions(+), 71 deletions(-) diff --git a/developers/doc-guidelines.md b/developers/doc-guidelines.md index e87fc01c..a6a229fa 100644 --- a/developers/doc-guidelines.md +++ b/developers/doc-guidelines.md @@ -14,82 +14,44 @@ 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. Contributions to the -documentation (both new content and edits of existing content) are welcome! +documentation rather than relying solely on the Web. -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]. (We provide a detailed -walkthrough of this process below.) +The documentation is a community effort in which 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 new +content and to edit existing content. -Style Guidelines ----------------- - - * Familiarize yourself with the terms defined in the [glossary]. Use these - terms consistently and accurately throughout your writing. - - -Markdown Conventions +How to Report Issues -------------------- -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.) +To report an issue, please create an issue in [qubes-issues], but before you do, +please make sure your issue 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. -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. - - -How to Contribute Using GitHub ------------------------------- +How to Contribute +----------------- 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 -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. +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][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. +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): @@ -144,12 +106,62 @@ pull request, we'll post a comment explaining why we can't. ![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]: 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-pull]: https://help.github.com/articles/using-pull-requests/ -[patch]: /doc/SourceCode/#sending-a-patch -[lists]: https://www.qubes-os.org/doc/QubesLists/ -[github]: https://github.com/ +[GitHub]: https://github.com/ +[md]: https://daringfireball.net/projects/markdown/ [git-commit]: http://chris.beams.io/posts/git-commit/