mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: removes writing guidelines, points contributors to Writers' Toolkit (#58011)
* removes writing guidelines, points contributors to the Writers' Toolkit * Update contribute/documentation/README.md Co-authored-by: Ursula Kallio <ursula.kallio@grafana.com> Co-authored-by: Ursula Kallio <ursula.kallio@grafana.com>
This commit is contained in:
Christopher Moyer
GitHub
parent
ea8c5ce929
commit
088a4e02e8
@ -11,7 +11,6 @@ This directory contains guides for contributors to the Grafana project.
|
||||
The `style-guides` directory contains style guides for the Grafana software project and documentation.
|
||||
|
||||
- [Backend style guide](style-guides/backend.md) for how to style and format backend functionality and code.
|
||||
- [Documentation style guide](style-guides/documentation-style-guide.md) for how to style and format documentation.
|
||||
- [Frontend style guide](style-guides/frontend.md) for how to style and format the user-facing functionality and code.
|
||||
- [Redux framework](style-guides/redux.md) for designing the Grafana redux framework.
|
||||
- [Themes style guide](style-guides/themes.md) for designing and updating Grafana themes.
|
||||
|
||||
@ -1,235 +1,7 @@
|
||||
# Contribute to our documentation
|
||||
|
||||
We provide these guidelines to help our contributors make additions or corrections to our documentation.
|
||||
Welcome. We're glad you're here to help make our technical documentation even better.
|
||||
|
||||
## Welcome
|
||||
For our style guide and writing guidelines, see [Writers' Toolkit](https://grafana.com/docs/writers-toolkit/).
|
||||
|
||||
Welcome. We're glad you're here to help make our technical documentation even better. We develop content that leads our users to success using Grafana products. Technical accuracy is our primary consideration, and we value the use of inclusive language. We regard your feedback as a gift - thanks for reading through these guidelines.
|
||||
|
||||
### Intended audience
|
||||
|
||||
We write these guidelines for contributors who are interested in improving our technical content.
|
||||
|
||||
## Understanding the structure of Grafana documentation
|
||||
|
||||
All Grafana Enterprise and OSS documentation is located in the [Grafana open source project](https://github.com/grafana/grafana) GitHub repository: https://github.com/grafana/grafana/tree/main/docs/sources.
|
||||
|
||||
- The **sources** directory organizes content by topic areas, for example **administration** and **alerting**.
|
||||
- Topic directories include an `_index.md` file, which provides an overview of the topic, and optionally includes subtopics that provide more detail.
|
||||
|
||||
> The `_index.md` file is required.
|
||||
|
||||
### Writing in markdown
|
||||
|
||||
We write technical documentation using [Markdown](https://en.wikipedia.org/wiki/Markdown). We've put together a short guide to help you how to structure and format your content.
|
||||
|
||||
To access the markdown guide, refer to [Markdown style guide](documentation-markdown-guide.md).
|
||||
|
||||
## Ways to contribute
|
||||
|
||||
We're thrilled that you are considering contributing to the documentation. You can contribute content in the following ways:
|
||||
|
||||
- [Request a change](#request-a-change)
|
||||
- [Edit a topic](#edit-a-topic)
|
||||
- [Write a topic](#write-a-topic)
|
||||
|
||||
### Request a change
|
||||
|
||||
Request a change when you want to make a suggestion about a topic, but don't want to provide an edit that generates a pull request. Requesting a change gives you the freedom to express your ideas without committing language. Your suggestion can reflect a small change to wording or can reflect larger, more substantive changes.
|
||||
|
||||
GitHub captures your request as an **Issue** logged against the repository.
|
||||
|
||||
Before you begin:
|
||||
|
||||
- Create a GitHub account.
|
||||
|
||||
To request a change, complete the following steps:
|
||||
|
||||
1. While viewing the topic, click **Request a change**.
|
||||
|
||||
The Issue title auto-populates with the location of the file about which you are requesting a change.
|
||||
|
||||
|
||||
|
||||
2. Enter a change request description.
|
||||
|
||||
3. Add the **type/docs** label.
|
||||
|
||||
4. Click **Submit new issue**.
|
||||
|
||||
### Edit a topic
|
||||
|
||||
If you want to recommend a small change, such as suggesting a correction to a topic, you can edit the topic directly in GitHub. You are not required to fork and clone the repo to use this approach.
|
||||
|
||||
Other small changes might include:
|
||||
|
||||
- Adding steps to a task
|
||||
- Adding clarifying language to a concept
|
||||
- Providing an example
|
||||
|
||||
Before you begin:
|
||||
|
||||
- Create a GitHub account.
|
||||
|
||||
To edit a topic, complete the following steps:
|
||||
|
||||
1. While viewing the topic you want to edit, click **Edit this page**.
|
||||
|
||||
|
||||
|
||||
2. Add your changes to the topic.
|
||||
|
||||
3. Scroll to the bottom of the page and enter a branch name.
|
||||
|
||||
For example, enter `clarified dashboard panel definition`.
|
||||
|
||||
4. Click **Commit**.
|
||||
|
||||
GitHub prompts you to create a PR.
|
||||
|
||||
5. Complete the prompts provided in the body of the PR.
|
||||
|
||||
6. Click **Create pull request**.
|
||||
|
||||
### Write a topic
|
||||
|
||||
At Grafana Labs, we use the principles of topic-based authoring when we write technical documentation. Topic-based authoring provides guidelines for writing three _types_ of technical documentation: concept, task, and reference. Before you begin writing, establish the topic type you want to write.
|
||||
|
||||
#### Understanding topic types
|
||||
|
||||
Technical content is divided into three topic types: concept, task, and reference.
|
||||
|
||||
- **Concept**: A concept topic explains _what_ a feature (or idea) is, and why it is important.
|
||||
- **Task**: A task topic explains _how_ to complete an end user procedure in the system. Task topics contain steps.
|
||||
- **Reference** A reference topic contains lookup information that a user might consult when they complete a task. Documenting a list of values with descriptions is a common form of reference topic.
|
||||
|
||||
**Example**
|
||||
|
||||
Suppose you are writing content for a site called _Doggie handbook_. You might organize your topics like this:
|
||||
|
||||
**Concepts**
|
||||
|
||||
- What a dog is
|
||||
- Brief history of dogs
|
||||
- Why you might want a dog
|
||||
- Tasks dogs can be trained to do
|
||||
|
||||
**Tasks**
|
||||
|
||||
- Feed the dog
|
||||
- Groom the dog
|
||||
- Train the dog
|
||||
|
||||
**References**
|
||||
|
||||
- List of dog equipment you will need
|
||||
- Table of breeds that includes breed name, size range, short or long hair, and type of dog
|
||||
|
||||
#### Prepare your environment
|
||||
|
||||
Before you begin writing, we recommend that you fork and clone the Grafana repository so that you can use a text editor locally to create branches, commit your changes, and create a PR.
|
||||
|
||||
While this document doesn't include git commands or descriptions of Github operations, you might find these links useful.
|
||||
|
||||
- [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git): We store all source code, including documentation, in Git repositories.
|
||||
- [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo): Locate the repo you want to clone, and fork it.
|
||||
- [Clone a repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository): Clone the repository to your local machine.
|
||||
- [Create a branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging): Before you make change, create a branch. Do not push changes against the `main` branch.
|
||||
- [Create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request): After you add, commit, and push your changes, create a PR in Github.
|
||||
|
||||
#### Use a documentation template to contribute a topic
|
||||
|
||||
We have provided documentation templates that align with each topic type:
|
||||
|
||||
- [Concept](templates/doc-concept-template.md)
|
||||
- [Task](templates/doc-task-template.md)
|
||||
- [Reference](templates/doc-reference-template.md)
|
||||
|
||||
Each template provides additional usage and formatting guidelines. We recommend that you make a copy of whichever template you are using, then add content.
|
||||
|
||||
> Remove any unused content before you commit your changes.
|
||||
|
||||
#### View a local build
|
||||
|
||||
Prior to pushing your changes, you can view a local build of the documentation so that you can review your work.
|
||||
|
||||
To view a local build:
|
||||
|
||||
1. Install [Docker](https://www.docker.com/products/docker-desktop).
|
||||
|
||||
1. Run Docker.
|
||||
|
||||
1. Navigate to the **docs** root directory.
|
||||
|
||||
1. Run `make build`.
|
||||
|
||||
1. Open `localhost:3002` to review your changes.
|
||||
|
||||
## Push changes and create a PR
|
||||
|
||||
When you are ready for other people to review your work, perform the following tasks.
|
||||
|
||||
1. [Add](https://git-scm.com/docs/git-add) your changes, which prepares your content for the next commit.
|
||||
|
||||
1. [Commit](https://git-scm.com/docs/git-commit) your changes.
|
||||
|
||||
1. [Push](https://git-scm.com/docs/git-push) your changes to Github.
|
||||
|
||||
1. [Create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) in Github.
|
||||
|
||||
The docs build system automatically conducts a series of tests to ensure that the content doesn't conflict with other content in the docs repository.
|
||||
|
||||
### Understanding the PR review and approval workflow
|
||||
|
||||
When a PR is added to the repo with a label associated with `docs`, it will be reviewed by a member of the technical writing team. Depending on the size of the PR and the priority of other work, the PR will either be immediately reviewed and merged (minor fixes typically follow this pattern) or the PR will be triaged and placed in the backlog of work or moved into further development.
|
||||
|
||||
## Join our community
|
||||
|
||||
For general discussions on documentation, you’re welcome to join the `#docs` channel on our [public Grafana Slack](http://slack.raintank.io) team.
|
||||
|
||||
## Reference: Top five writing tips
|
||||
|
||||
While we don't provide a comprehensive style guide in this document, here's a few writing tips to help the writing process.
|
||||
|
||||
### Consider the audience
|
||||
|
||||
Write for an audience that is computer literate and has general technical knowledge, but is not necessarily familiar with Grafana or the finer points of observability.
|
||||
|
||||
Pretend you are explaining your topic to a brand new Grafana user or developer.
|
||||
|
||||
### Write clear and concise sentences and paragraphs
|
||||
|
||||
Use the following sentence structure when you write: _subject_—_verb_—_object_. If you are telling a user to do something, write an imperative sentence. For example “Enter the refresh rate time interval and click Save.”
|
||||
|
||||
- You can also start a sentence with an _if_ clause, which positions the condition before the action.
|
||||
- Limit the number of words in a sentence to 20..
|
||||
|
||||
### Use active voice
|
||||
|
||||
Active voice makes the performer of the action the subject
|
||||
of the sentence. When you write in passive voice, the recipient of the action (and not the performer) becomes the subject of the sentence.
|
||||
|
||||
Active-voice sentences are more direct and clearly identify _who_ is doing _what_. Not all tasks are completed by a user; sometimes the system can also be a performer (and by extension, the subject of the sentence). When you write in active voice you clearly make that distinction, which results in more engaging and less wordy content.
|
||||
|
||||
| Use (active) | Avoid (passive) |
|
||||
| ----------------------------------------------------- | -------------------------------------------------------------------- |
|
||||
| After you upgrade the software, restart the computer. | After the software has been upgraded, the computer can be restarted. |
|
||||
| Click **OK** to save the dashboard. | The dashboard is saved when the **OK** button is clicked. |
|
||||
| Create a dashboard. | A dashboard is created by you. |
|
||||
|
||||
### Avoid obscure non-English words and abbreviations
|
||||
|
||||
Users might be unfamiliar with some non-English words and abbreviations such as _per_, _vs_, and _via_. Latin abbreviations in particular, like _i.e._, _e.g._, and _etc._, are vague.
|
||||
|
||||
| Use | Don’t use |
|
||||
| ------------ | ----------- |
|
||||
| through | via |
|
||||
| that is | i.e. |
|
||||
| according to | per, as per |
|
||||
| and so on | etc. |
|
||||
|
||||
### Write self-contained topics
|
||||
|
||||
Thanks to search engines, every page in the documentation might be a reader's entry point. This means that each page needs to be self-contained and make sense on its own. The reader should not need to read other topics in order to perform the task or understand the concept.
|
||||
|
||||
However, try to be helpful and link to related information. Using the _Doggie handbook_ example, the concept topic that explains what dogs can be trained to do might link to the Train the dog task.
|
||||
If you're interested in contributing to the Writers' Toolkit, refer to the [Writers' Toolkit](https://github.com/grafana/writers-toolkit) repository.
|
||||
|
||||
@ -1,152 +0,0 @@
|
||||
# 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.
|
||||
|
||||
## Headers
|
||||
|
||||
In Markdown, the number of "#" symbols creates different heading levels, similar to HTML heading levels:
|
||||
|
||||
**Example**
|
||||
|
||||
- \# 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.
|
||||
|
||||
**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.
|
||||
|
||||
**Example:** GitHub-flavored markdown emoji should _only_ appear in specific cases.
|
||||
|
||||
## Links and references
|
||||
|
||||
Create links to other website by wrapping the display text in square brackets, and the web URL in curved brackets.
|
||||
|
||||
\[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.
|
||||
|
||||
## Block quotes
|
||||
|
||||
Include block quotes inside text using right-facing arrows:
|
||||
|
||||
**Example**
|
||||
|
||||
> Any important information
|
||||
> about emoji can be separated into
|
||||
> a blockquote.
|
||||
|
||||
## 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:
|
||||
|
||||
```
|
||||
function testNum(a) {
|
||||
if (a > 0) {
|
||||
return "positive";
|
||||
} else {
|
||||
return "NOT positive";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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) {
|
||||
if (a > 0) {
|
||||
return 'positive';
|
||||
} else {
|
||||
return 'NOT positive';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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 "|".
|
||||
|
||||
**Example**
|
||||
|
||||
Heading one | Heading two
|
||||
|
||||
\------------|------------
|
||||
|
||||
Cell one data| Cell two data
|
||||
|
||||
Will publish as:
|
||||
|
||||
| Heading one | Heading two |
|
||||
| ------------- | ------------- |
|
||||
| Cell one data | Cell two data |
|
||||
|
||||
## Lists
|
||||
|
||||
### Numbered lists
|
||||
|
||||
To avoid inconsistent list numbering, use repetitive list numbering:
|
||||
|
||||
\1. First
|
||||
|
||||
\1. Second
|
||||
|
||||
\1. Third
|
||||
|
||||
The list above will always display as:
|
||||
|
||||
1. First
|
||||
2. Second
|
||||
3. Third
|
||||
|
||||
### Unordered lists
|
||||
|
||||
Build a list of points - an unordered or unnumbered list - by using "\-" (hyphen) characters.
|
||||
|
||||
**Example**
|
||||
|
||||
- First
|
||||
- Another item
|
||||
- The last list item
|
||||
|
||||
## Images
|
||||
|
||||
_Do not_ use image shortcodes at this time.
|
||||
|
||||
Include images in a document using the following syntax:
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
> **Note:** Alt text does not appear when the user hovers the mouse over the image, but title text does.
|
||||
|
||||
**Examples:**
|
||||
|
||||
- \!\[Grafana logo](/link/to/grafanalogo/logo.png "Grafana logo")
|
||||
- \!\[Example](/static/img/docs/folder_name/alert_test_rule.png "Example title")
|
||||
|
||||
This follows the format of "!", alt text wrapped in "[]" and the link URL wrapped in "()".
|
||||
|
||||
You can also use HTML such as the following:
|
||||
|
||||
```
|
||||
<img src="example.png"
|
||||
alt="Example image"
|
||||
style="float: left; margin-right: 5px;" />
|
||||
```
|
||||
|
||||
In most cases, use the markdown syntax rather than the HTML syntax. Only use the HTML if you need to change the image in ways unsupported by Markdown.
|
||||
|
||||
## Comments
|
||||
|
||||
You can include comments that will not appear in published markdown using the following syntax:
|
||||
|
||||
\[comment]: <> (Comment text to display)
|
||||
|
||||
The word "comment" wrapped in "[]" followed by a ":", a space, "<>", and then the comment itself wrapped in "()".
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 182 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 179 KiB |
@ -1,42 +0,0 @@
|
||||
DELETE THIS LINE: If draft = false, then the document will not be built in the doc site. If the date is earlier than the build date, than the document will not show in the build site. Use these settings to control whether future content is shown in the doc site.
|
||||
+++
|
||||
draft = "false"
|
||||
date = "yyyy-mm-dd"
|
||||
title = "Title in sentence case"
|
||||
description = "Description in title case"
|
||||
keywords = ["grafana", "enter", "keywords", "here"]
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
name = "Name of topic"
|
||||
identifier = "identifier"
|
||||
parent = "menu parent"
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Concept
|
||||
|
||||
The title of the concept topic will generally be a noun or a gerund. Examples include Templates, Templating, Dashboards, and panels.
|
||||
|
||||
Concepts are topic types for any information that doesn't involve task lists or reference information. Ideally you use concept elements to explain concepts, ideas, overviews, workflows, and the like. In the intro section, this first paragraph or two, you should explain to the user what to expect in this topic or section.
|
||||
|
||||
[Permissions overview](https://grafana.com/docs/grafana/latest/permissions/overview/) is an example of a concept topic.
|
||||
|
||||
## Idea
|
||||
|
||||
Concept topics or sections explain _what_ and _why_. They do not explain _how_. If you are a new user, you might look for concept information to learn about what Grafana is, why it might be useful to you, and what the general workflow is.
|
||||
|
||||
## Workflow
|
||||
|
||||
Continuing the example in the previous section, here is a sample Grafana workflow.
|
||||
|
||||
1. Install Grafana. <link to task for installing Grafana>
|
||||
1. Set up data sources. <link to data sources concept topic, which links to data source task topics>
|
||||
1. Create panels. <link to panel concept topic, which links to tasks>
|
||||
1. Create dashboards. <link to panel concept topic, which links to tasks>
|
||||
1. Enter queries. <link to query editor concept topic>
|
||||
1. Add users. <link to user management concept topic, which links to tasks>
|
||||
1. Create playlists. <link to Playlist topic that contains concept information and tasks>
|
||||
|
||||
## Next steps
|
||||
|
||||
Concept tasks often link to related information, including _tasks_ related to the concept and _reference_ topics related to the concept.
|
||||
@ -1,75 +0,0 @@
|
||||
DELETE THIS LINE: If draft = false, then the document will not be built in the doc site. If the date is earlier than the build date, than the document will not show in the build site. Use these settings to control whether future content is shown in the doc site.
|
||||
+++
|
||||
draft = "false"
|
||||
date = "yyyy-mm-dd"
|
||||
title = "Title in sentence case"
|
||||
description = "Description in title case"
|
||||
keywords = ["grafana", "enter", "keywords", "here"]
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
name = "Name of topic"
|
||||
identifier = "identifier"
|
||||
parent = "menu parent"
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Reference
|
||||
|
||||
The _reference_ topic type is for storing reference information, such as extensive tables, lists, or other information that is used as support for a task. Reference topics are also designed for API information.
|
||||
|
||||
Often reference topics are linked from _task_ topics, because they contain information the user needs in order to perform a task.
|
||||
|
||||
[Grafana CLI](https://grafana.com/docs/grafana/latest/administration/cli/) is one example of a reference topic.
|
||||
|
||||
## Lists
|
||||
|
||||
Lists of commands or parameters are often organized in reference topics. The information you need to present will dictate the format.
|
||||
|
||||
- They might
|
||||
- be in
|
||||
- unordered lists.
|
||||
|
||||
[Configuration](https://grafana.com/docs/grafana/latest/installation/configuration/) is an example of lists.
|
||||
|
||||
## Tables
|
||||
|
||||
If you have a large list of things to store in a table, then you are probably dealing with reference information. Hugo accepts either tables in Markdown or in HTML format, so use whichever is easier for you.
|
||||
|
||||
The [Glossary](https://grafana.com/docs/grafana/latest/guides/glossary/) provides an example of reference data in a table.
|
||||
|
||||
### Empty markdown table
|
||||
|
||||
While you might not need a heading for each table, headings are a good way to chunk information if you have several tables. They also make the content easy to skim. Use headings or intro paragraphs like this one to explain to the reader what the information in the table is used for.
|
||||
|
||||
| | | | | | |
|
||||
| :-- | :-- | :-: | :-: | --: | --: |
|
||||
| | | | | | |
|
||||
| | | | | | |
|
||||
| | | | | | |
|
||||
| | | | | | |
|
||||
|
||||
### Empty HTML table
|
||||
|
||||
And here is intro text, similar to the paragraph in the previous section. Do not add local styling to the table. The website CSS will take care of that for you.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Firstname</th>
|
||||
<th>Lastname</th>
|
||||
<th>Age</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Jill</td>
|
||||
<td>Smith</td>
|
||||
<td>50</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Eve</td>
|
||||
<td>Jackson</td>
|
||||
<td>94</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## API documentation
|
||||
|
||||
API documentation is always a reference topic rather than a task topic, but it has its own rules.
|
||||
@ -1,57 +0,0 @@
|
||||
+++
|
||||
draft = "false"
|
||||
date = "yyyy-mm-dd"
|
||||
title = "Title in sentence case"
|
||||
description = "Description in title case"
|
||||
keywords = ["grafana", "enter", "keywords", "here"]
|
||||
type = "docs"
|
||||
[menu.docs]
|
||||
name = "Name of topic"
|
||||
identifier = "identifier"
|
||||
parent = "menu parent"
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Task
|
||||
|
||||
A _task_ topic is intended for a procedure that describes how to accomplish a task. It lists a series of steps that users follow to produce an intended outcome. It tells the reader _how_ to do something. [Install Grafana plugins](https://grafana.com/docs/grafana/latest/plugins/installation/) and [Playlist](https://grafana.com/docs/grafana/latest/reference/playlist/) are examples of task topics. Playlist includes a small amount of concept information in the introduction, which is appropriate.
|
||||
|
||||
Always include an introduction of a short paragraph or two to explain what the task is for, perhaps give the reader an idea of what the outcome will be.
|
||||
|
||||
In most cases, each topic should only contain one task. If you have several very short, related tasks, then you might combine them into one topic.
|
||||
|
||||
In the case of a long task, then you probably won't need any headings except for the h1 at the top of the page.
|
||||
|
||||
1. Start with step one.
|
||||
1. Use second-person imperative tense.
|
||||
1. Basically, "You, do this" with every sentence.
|
||||
1. Do not use the third-person "user" for steps you want the reader ("you") to perform.
|
||||
1. Write steps that contain one action, possibly two related actions, such as copy and paste a thing or save and quit the program.
|
||||
If a sentence is not telling the reader to do something, then it is not a step. You can use nested images or paragraphs like this one to add information if necessary.
|
||||
|
||||
In many cases, you should tell the reader what the outcome should be so that they know when they are done.
|
||||
|
||||
## One-step task
|
||||
|
||||
Some tasks are so short, they only contain one step.
|
||||
|
||||
Write one-step tasks as simple sentences, not as unordered lists or numbered lists.
|
||||
|
||||
## Short task
|
||||
|
||||
Short tasks can be grouped. How short constitutes "short" is a judgment call based on number of steps and how long individual steps are.
|
||||
|
||||
1. Use your judgment.
|
||||
1. Ask your coworkers or someone on the Comm team for advice if you aren't sure.
|
||||
|
||||
## Next steps
|
||||
|
||||
If the task you are writing leads naturally to one or more other tasks, then include links after the task to help the reader figure out where to go next.
|
||||
|
||||
Thanks to internet search engines, every page in the documentation could be page one. Pretend you are explaining your task to a new Grafana user who just walked in off the street.
|
||||
|
||||
## Testing
|
||||
|
||||
It is a good practice to have someone else test the task you have written. If they can successfully complete the task using _only_ what the steps you have written, not guessing or using their inherent knowledge, then your task has passed the test. However, it is very common to find you have skipped steps, because _you_ are very familiar with Grafana and the topic you are explaining.
|
||||
|
||||
New users or people from other teams are very helpful for these tests.
|
||||
@ -1,345 +0,0 @@
|
||||
# Documentation style guide
|
||||
|
||||
This style guide applies to all documentation created for Grafana products.
|
||||
|
||||
For information about how to write technical documentation, refer to the following resources:
|
||||
|
||||
- [Google Technical Writing courses](https://developers.google.com/tech-writing)
|
||||
- [Divio documentation system](https://documentation.divio.com/)
|
||||
- [Vue writing principles](https://v3.vuejs.org/guide/contributing/writing-guide.html#principles)
|
||||
|
||||
## Contributing
|
||||
|
||||
The _Documentation style guide_ is a living document. Add to it whenever a style decision is made or a question is answered regarding style, grammar, or word choice.
|
||||
|
||||
## Published guides
|
||||
|
||||
For all items that are not covered in this guide, refer to the [Google developer documentation style guide](https://developers.google.com/style) and the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/welcome/), in that order.
|
||||
|
||||
## Spelling
|
||||
|
||||
To catch common misspellings, the [codespell](https://github.com/codespell-project/codespell) tool is run for every change.
|
||||
|
||||
## Inclusive language
|
||||
|
||||
Avoid using charged language.
|
||||
|
||||
### Allowing and blocking
|
||||
|
||||
When referring to _allowing_ or _blocking_ content or traffic, use a form of _allow_ or _block_:
|
||||
|
||||
- (noun) _allowlist_ or _blocklist_
|
||||
- (verb) _allow_ or _block_
|
||||
|
||||
Example: _To **allow** outgoing traffic, add the IP to the **allowlist**._
|
||||
|
||||
Avoid _whitelist_ or _blacklist_.
|
||||
|
||||
### Primary and secondary
|
||||
|
||||
To describe relationships between nodes or processes, there are several options:
|
||||
|
||||
- Use _primary_, _main_, or _parent_, instead of _master_.
|
||||
- Use _secondary_, _replica_, or _child_, instead of _slave_.
|
||||
|
||||
Avoid _master_ or _slave_.
|
||||
|
||||
## Grafana-specific style
|
||||
|
||||
The following guidelines are specific to Grafana documentation. For the most part, these are _guidelines_ are not rigid rules. If you have questions, then please ask in the #docs channel of Grafana Slack.
|
||||
|
||||
### General
|
||||
|
||||
Per the [Voice and tone](https://developers.google.com/style/tone) section of the Google developer documentation style guide:
|
||||
|
||||
> In your documents, aim for a voice and tone that's conversational, friendly, and respectful without being overly colloquial or frivolous; a voice that's casual and natural and approachable, not pedantic or pushy. Try to sound like a knowledgeable friend who understands what the developer wants to do.
|
||||
|
||||
- Use active voice:
|
||||
- Active: Grafana displays the heatmap visualization.
|
||||
- Passive: The heatmap visualization is displayed.
|
||||
- Write directly to the reader:
|
||||
- Use: "After you create a dashboard, you can add a panel to it."
|
||||
- Avoid: "After you create a dashboard, it is possible to add a panel to it."
|
||||
- Write in the imperative second person:
|
||||
- "Click the panel."
|
||||
- "Close the window."
|
||||
- Write in present tense:
|
||||
- Use: "The panel opens."
|
||||
- Avoid: "The panel will open."
|
||||
- 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 jargon or slang.
|
||||
- Do not use two spaces after a period; use one space after a sentence.
|
||||
- Remove any extra space characters at the end of a paragraph.
|
||||
- Aim for your sentences to be fewer than 25 words. Instead, use smaller complete phrases or change the format, such as using a list.
|
||||
- Aim for paragraphs to be three sentences or fewer. Make the text more concise, use more headings, or both.
|
||||
|
||||
### File naming conventions
|
||||
|
||||
- Files that are displayed in the help system should have names that are all lowercase, no spaces. Use hyphens instead of spaces. Example: glossary.md
|
||||
- Documentation file names should match the title. **Note:** This only applies to new files at this time. Do not change the names of older files unless directed to do so.
|
||||
- Internal reference file names should be all uppercase except the file extension. Example: CONTRIBUTING.md
|
||||
- Image file names should be descriptive and unique. Also, add the software version number that the image applies to or the screenshot was taken in. Example: share-dashboard-link-7-3.png
|
||||
|
||||
### Headings
|
||||
|
||||
- Write headings in sentence case, not title case.
|
||||
- This is sentence case
|
||||
- This is Title Case
|
||||
- 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
|
||||
|
||||
#### Heading don'ts
|
||||
|
||||
- Avoid stacked headings, which is 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, h2 is a good order. Do not go h1, h2, h3, h2, h3, h2.
|
||||
- Avoid using hyphens in headings.
|
||||
- Do not include parenthetical words like (Important!) in headings.
|
||||
|
||||
#### Step-by-step headings
|
||||
|
||||
In most cases, headings should not be numbered steps.
|
||||
|
||||
However, sometimes we need to use headings as numbered steps. This is mostly in cases where each step is complex or a series of other procedures. For example, in [Getting started with Grafana and Prometheus](https://grafana.com/docs/grafana/latest/getting-started/getting-started-prometheus/).
|
||||
|
||||
If that is the case, then use the following format for headings:
|
||||
|
||||
##### Step 1. Install the software
|
||||
|
||||
##### Step 2. Run the software
|
||||
|
||||
### 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.
|
||||
- _Do not_ use image shortcodes. Follow the guidance in [Markdown style guide](../documentation/documentation-markdown-guide.md#Images).
|
||||
- Markdown image links are preferred. Only use the HTML image links if you need to style the image in ways unsupported in Markdown.
|
||||
- When you name a file, follow the [file naming conventions](#file-naming-conventions). Example: image-name-7-3.png
|
||||
|
||||
### Unordered lists
|
||||
|
||||
Here are a few general rules about unordered lists. For more guidance, refer to [Lists](https://developers.google.com/style/lists) in the [Google developer style guide](https://developers.google.com/style/).
|
||||
|
||||
- List items should begin with a capital letter unless there is a strong reason not to. For example, you are listing case-sensitive parameters.
|
||||
- List items should end with periods if they are complete sentences. If one item in a list ends with a period, then apply periods to all of them.
|
||||
|
||||
### 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"
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
#### Git, GitHub
|
||||
|
||||
Git is always capitalized, unless part of a code block. GitHub is the correct spelling and capitalization.
|
||||
|
||||
#### Integrations
|
||||
|
||||
In general, "integration" is not capitalized. Only capitalize it if it is capitalized in the UI or part of a proper noun, like the name of a specific integration.
|
||||
|
||||
The first letter of the name of an integration is always capitalized, even if the original named source is lowercase.
|
||||
|
||||
**Examples:**
|
||||
|
||||
- MySQL Integration
|
||||
- CockroachDB Integration
|
||||
- Etcd Integration
|
||||
- I installed an integration on my local Grafana.
|
||||
|
||||
#### Kubernetes objects
|
||||
|
||||
Capitalize Kubernetes objects such as Job, Pod, and StatefulSet when it is clear you are specifically talking about them and not generic jobs, pods, or whatever.
|
||||
|
||||
Introduce the object as "Kubernetes XX" on the first usage, then just the object in subsequent uses.
|
||||
|
||||
**Example:**
|
||||
|
||||
Create the Kubernetes Job and check the logs to retrieve the generated token:
|
||||
|
||||
The Job requires the token be submitted as …
|
||||
|
||||
### Links and references
|
||||
|
||||
When referencing another document, use "Refer to" rather than alternatives such as "See" or "Check out."
|
||||
|
||||
Always give the reader some idea of what to expect in the reference. Avoid blind references, such as, "Refer to [this file](link)."
|
||||
|
||||
When possible, use the exact title of the page or section you are linking to as the link text.
|
||||
|
||||
**Example**
|
||||
Refer to the [Documentation style guide](documentation-style-guide.md) for information about word usage and capitalization guidelines.
|
||||
|
||||
### Notes, tips, cautions, and warnings
|
||||
|
||||
Grafana documentation uses notes, tips, cautions, and warnings. Notes are the most common. The format for all of them is indented, bold, sentence case:
|
||||
|
||||
```
|
||||
> **Note:**
|
||||
```
|
||||
|
||||
#### Notes
|
||||
|
||||
Notes provide additional information that the user should be extra aware of. For example:
|
||||
|
||||
> **Note:** This page describes a feature for Grafana 7.0 beta.
|
||||
|
||||
#### Tips
|
||||
|
||||
Tips describe alternate or more efficient ways of doing things. Rarely used.
|
||||
|
||||
#### Cautions
|
||||
|
||||
Cautions warn the user that they should proceed with caution. Use cautions to emphasize the potential downside of a course of action.
|
||||
|
||||
> **Caution:** If you turn off authentication requirements, then anyone can access your Grafana instance. This poses a considerable security risk.
|
||||
|
||||
#### Warnings
|
||||
|
||||
Warnings tell the user not to do something. For example:
|
||||
|
||||
> **Warning:** Grafana does not back up your dashboards. If you delete a dashboard, then you might not be able to recover it.
|
||||
|
||||
### 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 add `$` before commands. Make it easy for users to copy and paste commands.
|
||||
|
||||
- **Right:** `sudo yum install grafana`
|
||||
- **Wrong:** `$ sudo yum install grafana`
|
||||
|
||||
- Include `sudo` before commands that require `sudo` to work.
|
||||
|
||||
For terminal examples and Grafana configuration, use a `bash` code block:
|
||||
|
||||
```bash
|
||||
sudo yum install grafana
|
||||
```
|
||||
|
||||
For HTTP request/response, use an `http` code block:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/id/1/permissions HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
### Word usage
|
||||
|
||||
Grafana products has some words, abbreviations, and terms particular to the Grafana discourse community.
|
||||
|
||||
#### changelog
|
||||
|
||||
One word, not two.
|
||||
|
||||
**Example**
|
||||
|
||||
- Read the full changelog.
|
||||
|
||||
**Exception:**
|
||||
|
||||
- When referring to the file containing the official changelog, use the filename: `CHANGELOG.md`.
|
||||
|
||||
#### checkout, check out
|
||||
|
||||
Two words if used as a verb, one word if used as a noun.
|
||||
|
||||
**Examples**
|
||||
|
||||
- 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.
|
||||
|
||||
#### 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.
|
||||
|
||||
#### drawer
|
||||
|
||||
Do not use. This is developer jargon that refers to a UI panel. Refer to the panel or feature by its proper name.
|
||||
|
||||
#### intro, introduction
|
||||
|
||||
"Introduction" is the preferred word. Use "intro" if there are space constraints (like on the side menu) or you are specifically trying for a less formal, more conversational tone.
|
||||
|
||||
#### metadata
|
||||
|
||||
One word, not two.
|
||||
|
||||
#### mixin
|
||||
|
||||
One word, not two. Also, not hyphenated.
|
||||
|
||||
#### open source, open-source
|
||||
|
||||
Do not hyphenate when used as an adjective unless the lack of hyphen would cause confusion. For example: _Open source software design is the most open open-source system I can imagine._
|
||||
|
||||
Do not hyphenate when it is used as a noun. For example: _Open source is the best way to develop software._
|
||||
|
||||
#### plugin, plug in
|
||||
|
||||
Two words if used as a verb, one word if used as a noun. Do not use _plug-in_.
|
||||
|
||||
**Examples**
|
||||
|
||||
- Plug in the appliance.
|
||||
- Download the plugin.
|
||||
|
||||
#### setup, set up
|
||||
|
||||
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.
|
||||
|
||||
#### node_exporter, windows_exporter
|
||||
|
||||
When referencing the Prometheus data source exporters, always use "node_exporter" and "windows_exporter" when referring to those tools.
|
||||
|
||||
**Correct:** node_exporter, windows_exporter
|
||||
**Incorrect:** Node Exporter, node exporter, Windows Exporter, Windows exporter, windows exporter.
|
||||
|
||||
#### web server
|
||||
|
||||
Two words, not one.
|
||||
|
||||
**Correct:** web server
|
||||
**Incorrect:** webserver
|
||||
|
||||
### MS SQL Server
|
||||
|
||||
Always use "MS SQL" when referring to MS SQL Server application.
|
||||
|
||||
Incorrect UI spellings will be corrected in a later version of Grafana.
|
||||
Loading…
Reference in New Issue
Block a user