diff --git a/developer/general/documentation-style-guide.md b/developer/general/documentation-style-guide.md index 45064074..4d23390f 100644 --- a/developer/general/documentation-style-guide.md +++ b/developer/general/documentation-style-guide.md @@ -85,7 +85,7 @@ 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). In particular, never include HTML or CSS for styling, +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 @@ -118,6 +118,124 @@ for a list of supported languages). Use `[...]` for anything omitted. Hard wrap Markdown lines at 80 characters, unless the line can't be broken (e.g., code or a URL). +### Do not use Markdown syntax for styling + +For example, there is a common temptation to use block quotes (lines beginning +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! +``` + +This renders as: + +> Note: This is an important note! + +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. + +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.,: + +``` +**Note:** This is an important note. +``` + +This renders as: + +**Note:** This is an important note. + +### 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: + +``` + + + + + + + +``` + +These render as: + + + + + + + + + ## Writing guidelines ### Correct use of terminology