Writing for the docs sites

When writing for the documentation sites, follow the Google developer documentation style guide, except in the cases where the Dash docs guidelines conflict with it.

To make PR review, diff resolution, and history tracking easier, use semantic breaks when writing Markdown. Reference the full specification for helps, but roughly follow these guidelines:

• Keep each line 80 characters or fewer.
• Break lines at sentences and, unless the sentence is very short, on phrases within sentences.
• When it's necessary to split a sentence across lines, try to pick a break that makes it clear that the line continues on the next line. That way future editors and reviewers are more likely to notice that the edit might affect another line.

Incorporating semantic breaks in your writing might feel tedious at first, but quickly proves helpful and becomes natural. Don't worry about getting the breaks perfect or completely consistent, any effort towards their semantic nature is extremely helpful.

For some more discussion about the origin of this technique, also check out Brandon Rhode's Semantic Linefeeds post.

Use descriptive link text that follows the Google guidelines on Cross-references and linking.

For easier editing, shorter lines, and reduced duplication, prefer using Markdown link references instead of inline links.

Place the link definitions at the end of the current section where they're used, before the next header.

If a link definition is used multiple times across a page, you can place it at the bottom of the document.

If you want a link to open in a new tab by default, add the target="_blank" and rel="noopener" attributes.

For Markdown links:

[Link text][link-ref]{: target="_blank" rel="noopener"}

For HTML links:

<a href="#link-ref" target="_blank" rel="noopener">Link text</a>