From 0c29e05f3ded851c0e6acb894dcbc33318277d31 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 3 Feb 2018 15:08:05 -0600 Subject: [PATCH] Update Markdown Conventions - Add convention for using relative rather than absolute paths - Follow the convention to insert a newline at the end of each sentence - Note the class of exceptions to the aforementioned convention --- basics_user/doc-guidelines.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index 2c34e0c4..27869f28 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -146,25 +146,25 @@ Style Guidelines Markdown Conventions -------------------- -All the documentation is written in Markdown for maximum accessibility. When -making contributions, please try to observe the following style 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. + * 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 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` @@ -188,5 +188,8 @@ Please try to write good commit messages, according to the [gh-pull]: https://help.github.com/articles/using-pull-requests/ [GitHub]: https://github.com/ [mailing lists]: /mailing-lists/ +[QSBs]: /security/bulletins/ +[News]: /news/ [md]: https://daringfireball.net/projects/markdown/ [git-commit]: /doc/coding-style/#commit-message-guidelines +