diff --git a/developer/general/documentation-style-guide.md b/developer/general/documentation-style-guide.md index f76a7061..84881663 100644 --- a/developer/general/documentation-style-guide.md +++ b/developer/general/documentation-style-guide.md @@ -13,88 +13,52 @@ title: Documentation style guide _Also see [how to edit the documentation](/doc/how-to-edit-the-documentation/)._ -Qubes OS documentation pages are stored as plain text Markdown files in the -[qubes-doc](https://github.com/QubesOS/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. +Qubes OS documentation pages are stored as plain text Markdown files in the [qubes-doc](https://github.com/QubesOS/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 volunteer community effort. People like you are -constantly working to make it better. If you notice something that can be fixed -or improved, please [edit the -documentation](/doc/how-to-edit-the-documentation/)! +The documentation is a volunteer community effort. People like you are constantly working to make it better. If you notice something that can be fixed or improved, please [edit the documentation](/doc/how-to-edit-the-documentation/)! -This page explains the standards we follow for writing, formatting, and -organizing the documentation. Please follow these guidelines and conventions -when editing the documentation. For the standards governing the website as a -whole, please see the [website style guide](/doc/website-style-guide). +This page explains the standards we follow for writing, formatting, and organizing the documentation. Please follow these guidelines and conventions when editing the documentation. For the standards governing the website as a whole, please see the [website style guide](/doc/website-style-guide). ## Markdown conventions -All the documentation is written in Markdown for maximum accessibility. When -making contributions, please observe the following style conventions. If you're -not familiar with Markdown syntax, -[this](https://daringfireball.net/projects/markdown/) is a great resource. +All the documentation is written in Markdown for maximum accessibility. When making contributions, please observe the following style conventions. If you're not familiar with Markdown syntax, [this](https://daringfireball.net/projects/markdown/) is a great resource. ### Hyperlink syntax -Use non-reference-style links like `[website](https://example.com/)`. Do *not* -use reference-style links like `[website][example]`, `[website][]` or -`[website]`. This facilitates the localization process. +Use non-reference-style links like `[website](https://example.com/)`. Do *not* use reference-style links like `[website][example]`, `[website][]` or `[website]`. This facilitates the localization process. ### Relative vs. absolute links -Always use relative rather than absolute paths for internal website links. For -example, use `/doc/documentation-style-guide/` instead of -`https://www.qubes-os.org/doc/documentation-style-guide/`. +Always use relative rather than absolute paths for internal website links. For example, use `/doc/documentation-style-guide/` instead of `https://www.qubes-os.org/doc/documentation-style-guide/`. You may use absolute URLs in the following cases: - External links -- URLs that appear inside code blocks (e.g., in comments and document - templates, and the plain text reproductions of [QSBs](/security/qsb/) and - [Canaries](/security/canary/)), since they're not hyperlinks -- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part - of the website itself but rather of the auxiliary infrastructure supporting - the website +- URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of [QSBs](/security/qsb/) and [Canaries](/security/canary/)), since they're not hyperlinks +- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part of the website itself but rather of the auxiliary infrastructure supporting the website -This rule is important because using absolute URLs for internal website links -breaks: +This rule is important because using absolute URLs for internal website links breaks: - Serving the website offline - Website localization - Generating offline documentation -- Automatically redirecting Tor Browser visitors to the correct page on the - onion service mirror +- Automatically redirecting Tor Browser visitors to the correct page on the onion service mirror ### Image linking -See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) -for the required syntax. This will make the image a hyperlink to the image -file, allowing the reader to click on the image in order to view the full image -by itself. This is important. Following best practices, our website has a -responsive design, which allows the website to render appropriately across all -screen sizes. When viewing this page on a smaller screen, such as on a mobile -device, the image will automatically shrink down to fit the screen. If visitors -cannot click on the image to view it in full size, then, depending on their -device, they may have no way see the details in the image clearly. +See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly. -In addition, make sure to link only to images in the -[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do -not attempt to link to images hosted on other websites. +In addition, make sure to link only to images in the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do not attempt to link to images hosted on other websites. ### HTML and CSS -Do not write HTML inside Markdown documents (except in rare, unavoidable cases, -such as [alerts](#alerts)). In particular, never include HTML or CSS for styling, -formatting, or white space control. That belongs in the (S)CSS files instead. +Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as [alerts](#alerts)). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead. ### Headings -Do not use `h1` headings (single `#` or `======` underline). These are -automatically generated from the `title:` line in the YAML front matter. +Do not use `h1` headings (single `#` or `======` underline). These are automatically generated from the `title:` line in the YAML front matter. -Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use -underlining syntax (`-----`). +Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use underlining syntax (`-----`). ### Indentation @@ -102,27 +66,19 @@ Use spaces instead of tabs. Use hanging indentations where appropriate. ### Lists -If appropriate, make numerals in numbered lists match between Markdown source -and HTML output. Some users read the Markdown source directly, and this makes -numbered lists easier to follow. +If appropriate, make numerals in numbered lists match between Markdown source and HTML output. Some users read the Markdown source directly, and this makes numbered lists easier to follow. ### Code blocks -When writing code blocks, use [syntax -highlighting](https://github.github.com/gfm/#info-string) where possible (see -[here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) -for a list of supported languages). Use `[...]` for anything omitted. +When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where possible (see [here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) for a list of supported languages). Use `[...]` for anything omitted. ### Line wrapping -Hard wrap Markdown lines at 80 characters, unless the line can't be broken -(e.g., code or a URL). +Do not hard wrap text, except where necessary (e.g., inside code blocks). ### Do not use Markdown syntax for styling -For example, there is a common temptation to use block quotations (created by -beginning lines with the `>` character) in order to stylistically distinguish -some portion of text from the rest of the document, e.g.: +For example, there is a common temptation to use block quotations (created by beginning lines with the `>` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.: ``` > Note: This is an important note! @@ -134,20 +90,11 @@ This renders as: There are two problems with this: -1. It is a violation of the [separation of content and - presentation](https://en.wikipedia.org/wiki/Separation_of_content_and_presentation), - since it abuses markup syntax in order to achieve unintended stylistic - results. The Markdown (and HTML, if any) should embody the *content* of the - documentation, while the *presentation* is handled by (S)CSS. +1. It is a violation of the [separation of content and presentation](https://en.wikipedia.org/wiki/Separation_of_content_and_presentation), since it abuses markup syntax in order to achieve unintended stylistic results. The Markdown (and HTML, if any) should embody the *content* of the documentation, while the *presentation* is handled by (S)CSS. -2. It is an abuse of quotation syntax for text that is not actually a - quotation. (You are not quoting anyone here. You're just telling the reader - to note something and trying to draw their attention to your note visually.) +2. It is an abuse of quotation syntax for text that is not actually a quotation. (You are not quoting anyone here. You're just telling the reader to note something and trying to draw their attention to your note visually.) -Instead, an example of an appropriate way to stylistically distinguish a -portion of text is by using [alerts](#alerts). Consider also that extra styling -and visual distinction may not even be necessary. In most cases, traditional -writing methods are perfectly sufficient, e.g.,: +Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using [alerts](#alerts). Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,: ``` **Note:** This is an important note. @@ -159,14 +106,7 @@ This renders as: ### Alerts -Alerts are sections of HTML used to draw the reader's attention to important -information, such as warnings, and for stylistic purposes. They are typically -styled as colored text boxes, usually accompanied by icons. Alerts should -generally be used somewhat sparingly, so as not to cause [alert -fatigue](https://en.wikipedia.org/wiki/Alarm_fatigue) and since they must be -written in HTML instead of Markdown, which makes the source less readable and -more difficult to work with for localization and automation purposes. Here are -examples of several types of alerts and their recommended icons: +Alerts are sections of HTML used to draw the reader's attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons. Alerts should generally be used somewhat sparingly, so as not to cause [alert fatigue](https://en.wikipedia.org/wiki/Alarm_fatigue) and since they must be written in HTML instead of Markdown, which makes the source less readable and more difficult to work with for localization and automation purposes. Here are examples of several types of alerts and their recommended icons: ```