IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Refactor inconsistent unordered lists (#27826)

Browse Source 
* Docs: Refactor inconsistent unordered lists

* add requested changes

* Update docs/sources/linking/data-link-variables.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/http_api/_index.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/guides/whats-new-in-v6-0.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/auth/auth-proxy.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* resolve weird line breaks

* revert unintentional change

* Update docs/sources/auth/auth-proxy.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/auth/auth-proxy.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/auth/auth-proxy.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
This commit is contained in:
John S
2020-10-02 13:02:11 -05:00
committed by GitHub
parent 7d7e727f22
commit 4d3067e139
49 changed files with 735 additions and 745 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
contribute/style-guides/documentation-markdown-guide.md
View File

@@ -1,30 +1,26 @@
# Markdown style guide
This guide for Markdown style helps keep contributions consistent across all documentation
created for Grafana products. Refer to the guide and update its sections as needed when a
Subject Matter Expert answers a question on Markdown style, or a decision is made about
how to apply Markdown.
This guide for Markdown style helps keep contributions consistent across all documentation created for Grafana products. Refer to the guide and update its sections as needed when a Subject Matter Expert answers a question on Markdown style, or a decision is made about how to apply Markdown.
## Headers
In Markdown, the number of "#" symbols creates different heading levels, similar to
HTML heading levels:
In Markdown, the number of "#" symbols creates different heading levels, similar to HTML heading levels:
**Example**
* \# is \<h1>.
* \#\# is \<h2>.
* \#\#\# is \<h3>.
- \# is \<h1>.
- \#\# is \<h2>.
- \#\#\# is \<h3>.
Start your document with a single ``#`` for the title of the page. Add the sub-headings with two ``##``.
## Bold and emphasis
* Make text **bold** using two asterisks.
- Make text **bold** using two asterisks.
**Example:** It is ``**important**`` to use GitHub Flavored Markdown emoji consistently.
**Example:** It is ``**important**`` to use GitHub-flavored Markdown emoji consistently.
* Make text ``_emphasized_`` using single `` _underscores_``. Do not use the single asterisk, it can be easily confused with bold.
- Make text ``_emphasized_`` using single `` _underscores_``. Do not use the single asterisk, it can be easily confused with bold.
**Example:** GitHub-flavored markdown emoji should _only_ appear in specific cases.
@@ -35,7 +31,7 @@ Create links to other website by wrapping the display text in square brackets, a
\[text to display](www.website.com)
**Example:** For more information on including emoji in GitHub flavored Markdown, refer to the [webfx page on emoji](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of emoji.
**Example:** For more information on including emoji in GitHub-flavored markdown, refer to the [webfx page on emoji](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of emoji.
## Block quotes
@@ -49,8 +45,7 @@ Include block quotes inside text using right-facing arrows:
## Code blocks
Code blocks written with markdown can show off syntax highlighting specific
to different languages. Use three back tics to create a code block:
Code blocks written with markdown can show off syntax highlighting specific to different languages. Use three back tics to create a code block:
```
function testNum(a) {
@@ -62,8 +57,7 @@ function testNum(a) {
}
```
Write the name of the language after the first set of back tics, no spaces,
to show specific syntax highlighting. For example; "\```javascript" produces the following:
Write the name of the language after the first set of back tics, no spaces, to show specific syntax highlighting. For example; "\```javascript" produces the following:
```javascript
function testNum(a) {
@@ -76,10 +70,7 @@ function testNum(a) {
```
## Tables
Construct a table by typing the table headings, and separating them with
a "|" character. Then, add a second line of dashes ("-") separated by
another "|" character. When constructing the table cells, separate each cell data with another
"|".
Construct a table by typing the table headings, and separating them with a "|" character. Then, add a second line of dashes ("-") separated by another "|" character. When constructing the table cells, separate each cell data with another "|".
**Example**
@@ -115,8 +106,7 @@ The list above will always display as:
### Unordered lists
Build a list of points - an unordered or unnumbered list - by
using "\-" (hyphen) characters.
Build a list of points - an unordered or unnumbered list - by using "\-" (hyphen) characters.
**Example**

94
contribute/style-guides/documentation-style-guide.md
View File

@@ -26,8 +26,8 @@ This section provides guidelines on how to avoid using charged language in docum
Don't use "whitelist" or "blacklist" when referring to allowing or blocking content or traffic.
* When used as a noun, use "allowlist" or "blocklist".
* When used as a verb, use "allow" or "block"
- When used as a noun, use "allowlist" or "blocklist".
- When used as a verb, use "allow" or "block"
Example: _To **allow** outgoing traffic, add the IP to the **allowlist**._
@@ -35,8 +35,8 @@ Example: _To **allow** outgoing traffic, add the IP to the **allowlist**._
Don't use "master" or "slave" to describe relationships between nodes or processes.
* Use "leader", "main" or "primary," instead of "master."
* Use "follower" or "secondary," instead of "slave."
- Use "leader", "main" or "primary," instead of "master."
- Use "follower" or "secondary," instead of "slave."
### Exceptions
@@ -50,17 +50,17 @@ The following sections provide general guidelines on topics specific to Grafana
### General
* Use active voice. Avoid passive voice.
- Use active voice. Avoid passive voice.
- Passive: The heatmap visualization is displayed.
- Active: Grafana displays the heatmap visualization.
* Write in the imperative second person. Examples: You can write a query. Click the panel. Close the window.
* Write in present tense.
- Write in the imperative second person. Examples: You can write a query. Click the panel. Close the window.
- Write in present tense.
- Not: The panel will open.
- Use: The panel opens. Grafana opens the panel.
* Do not use an ampersand (&) as an abbreviation for "and."
- Do not use an ampersand (&) as an abbreviation for "and."
- **Exceptions:** If an ampersand is used in the Grafana UI, then match the UI.
* Avoid using internal slang and jargon in technical documentation.
* Do not use two spaces after a period. Only add one space after each sentence. Do not add a space at the end of the paragraph.
- Avoid using internal slang and jargon in technical documentation.
- Do not use two spaces after a period. Only add one space after each sentence. Do not add a space at the end of the paragraph.
### File naming conventions
@@ -70,39 +70,39 @@ The following sections provide general guidelines on topics specific to Grafana
### Headings
* Write headings in sentence case, not title case.
- Write headings in sentence case, not title case.
- This is sentence case
- This Is Title Case
* Task topic headings start with a verb.
- Task topic headings start with a verb.
- Write a query. Create a dashboard.
* Concept and reference topic headings should be nouns or gerunds. Examples: Contributing to docs, Visualizations, Style guide
* Avoid following one heading with another heading.
* Avoid skipping heading levels. For example, an h1 should be followed by an h2 rather than an h3.
* Avoid having just one lower-level heading. For example, h1, h2, h2, h3, h3, h2 is a good order. Do no go h1, h2, h3, h2, h3, h2.
* Don't include parenthetical words like (Important!) in headings.
- Concept and reference topic headings should be nouns or gerunds. Examples: Contributing to docs, Visualizations, Style guide
- Avoid following one heading with another heading.
- Avoid skipping heading levels. For example, an h1 should be followed by an h2 rather than an h3.
- Avoid having just one lower-level heading. For example, h1, h2, h2, h3, h3, h2 is a good order. Do no go h1, h2, h3, h2, h3, h2.
- Don't include parenthetical words like (Important!) in headings.
### Images
* Preferred format is .png
* File extension should be all lowercase.
* Preferred DPI is 72.
* Assume all graphics will be exclusively viewed on the web.
* Maximum image size is 3840px X 2160px.
* Screenshots should be readable, but not too large.
- Preferred format is .png
- File extension should be all lowercase.
- Preferred DPI is 72.
- Assume all graphics will be exclusively viewed on the web.
- Maximum image size is 3840px X 2160px.
- Screenshots should be readable, but not too large.
### Capitalization
* Grafana, Loki, and Prometheus are always capitalized unless part of a code block.
* API names are always Title Case, followed by "API"—for example, "Dashboard Permissions API"
* Git is always capitalized, unless part of a code block.
* Abbreviations are always capitalized (such as API, HTTP, ID, JSON, SQL, or URL) unless they are part of a code block.
* Menu and submenu titles always use sentence case: capitalize the first word, and lowercase the rest.
- Grafana, Loki, and Prometheus are always capitalized unless part of a code block.
- API names are always Title Case, followed by "API"—for example, "Dashboard Permissions API"
- Git is always capitalized, unless part of a code block.
- Abbreviations are always capitalized (such as API, HTTP, ID, JSON, SQL, or URL) unless they are part of a code block.
- Menu and submenu titles always use sentence case: capitalize the first word, and lowercase the rest.
- "Dashboards" when referring to the submenu title.
- "Keyboard shortcuts" when referring to the submenu topic.
* Generic and plural versions are always lowercase.
- Generic and plural versions are always lowercase.
- Lowercase "dashboard" when referring to a dashboard generally.
- Lowercase "dashboards" when referring to multiple dashboards.
* **Exceptions:** If a term is lowercased in the Grafana UI, then match the UI.
- **Exceptions:** If a term is lowercased in the Grafana UI, then match the UI.
### Links and references
@@ -147,14 +147,14 @@ Warnings tell the user not to do something. For example:
### Command line examples
* Do not assume everyone is using Linux. Make sure instructions include enough information for Windows and Mac users to successfully complete procedures.
- Do not assume everyone is using Linux. Make sure instructions include enough information for Windows and Mac users to successfully complete procedures.
* Do not add `$` before commands. Make it easy for users to copy and paste commands.
- Do not add `$` before commands. Make it easy for users to copy and paste commands.
* **Wrong:** `$ sudo yum install grafana`
* **Right:** `sudo yum install grafana`
- **Wrong:** `$ sudo yum install grafana`
- **Right:** `sudo yum install grafana`
* Include `sudo` before commands that require `sudo` to work.
- Include `sudo` before commands that require `sudo` to work.
For terminal examples and Grafana configuration, use a `bash` code block:
```bash
@@ -178,26 +178,26 @@ Two words if used as a verb, one word if used as a noun.
**Examples**
* Check out these new features!
* Proceed to checkout.
- Check out these new features!
- Proceed to checkout.
#### data source
Two words, not one
**Exceptions:**
* "datasource" used as an identifier
* "datasource" in a URL
* Use "data source" instead of "datasource" unless used as an identifier, in code, or as part of a URL.
* Spell out "repository" and avoid the shorter "repo."
* Use "Unix" as the preferred spelling (as opposed to "UNIX", or "unix") when referring to the family of operating systems.
- "datasource" used as an identifier
- "datasource" in a URL
- Use "data source" instead of "datasource" unless used as an identifier, in code, or as part of a URL.
- Spell out "repository" and avoid the shorter "repo."
- Use "Unix" as the preferred spelling (as opposed to "UNIX", or "unix") when referring to the family of operating systems.
#### display (verb)
*Display* is a transitive verb, which means it always needs a direct object.
* Correct, active voice: Grafana displays your list of active alarms.
* Correct, but passive voice: Your list of active alarms is displayed.
* Incorrect: The list of active alarms displays.
- Correct, active voice: Grafana displays your list of active alarms.
- Correct, but passive voice: Your list of active alarms is displayed.
- Incorrect: The list of active alarms displays.
#### drawer
@@ -223,5 +223,5 @@ Two words if used as a verb, one word if used as a noun.
**Examples**
* Set up the workspace.
* Initial setup might take five minutes.
- Set up the workspace.
- Initial setup might take five minutes.