-
Notifications
You must be signed in to change notification settings - Fork 54
Sensu docs style guide
Thank you for your interest in contributing to the Sensu docs! If you haven't yet, please read through our contributing guide and code of conduct. If you're new (Welcome!), check out the quick start and feel free to ask any questions by opening an issue or dropping by in #documentation in the Sensu community Slack.
The Sensu docs use US English, Hugo static site generation (including Blackfriday Markdown, Go templates, and Chroma syntax highlighting), TravisCI continuous integration, and Heroku deployment. Sensu docs style follows the internal Sensu voice, tone, and style guide and defaults to its recommendations.
- Quick start
- Page templates
- Code samples
- Multi-platform content
- Callouts
- Links
- Lists
- Formatting
- Writing style
- Acknowledgements
| Do | Don't |
|---|---|
| Say it clearly and plainly. | Use jargon or cultural references. |
| Make it obvious and scannable. | Write long paragraphs. |
| Refer to the reader as "you". | Overuse passive voice. |
Code samples
{{< code shell >}}
sensuctl entity list
{{< /code >}}
Links
See the [installation guide][1].
# Link to the current version in the current section
[1]: ../overview
# Link to the current version in another section
[1]: ../../installation/overview
Use numbers to reference links. When adding new content, it is not necessary to renumber links so that they are referenced in order in the body of the text. In other words, it is OK to list [linked text][10] before [linked text][1] in the body of the text.
Tables
heading | heading |
--------|---------|
text | text |
text | text |
See also the Sensu docs template.
All content pages must start with a frontmatter section.
---
title: "Installing and configuring Sensu 2.0"
linkTitle: "Installation and Configuration"
description: "The Sensu Core installation guide."
weight: 1
version: "2.0"
product: "Sensu Core"
platformContent: true
platforms: ["Ubuntu/Debian", "RHEL/CentOS", "Windows", "macOS", "Docker"]
toc: false
menu:
sensu-core-2.0:
parent: getting-started
---
| attribute | required? | description |
|---|---|---|
title |
X | The title that appears at the top of the page, in sentence case |
version |
X | The product version as corresponds to the site config file |
product |
X | The product name as corresponds to the site config file |
menu |
X | The location of the linkTitle in the sidebar according to product, version, and section name |
linkTitle |
The title that appears in the sidebar, in title case | |
description |
Description of the page used in the page metadata. Descriptions should describe what's on the page, include keywords where appropriate, include a CTA (ex: Read the docs to learn more.), and be about 300 characters. For example, this description is part of link unfurling in Slack. | |
weight |
Integer that controls the ordering of the page in the sidebar relative to other pages | |
platformContent |
Boolean indicating whether the page should include a platform-switching dropdown at the top of the page, default = false | |
platforms |
Array of comma-separated strings representing platform names | |
offline |
Boolean: true to include page in offline layout for PDF generation; false to exclude page from offline layout for PDF generation | |
toc |
Boolean: true to include a floating table of contents in right margin of the page; otherwise, false. Helpful for pages with too many level-2 headings to list (e.g. release notes). For pages that use this attribute, include a manual table of contents at the top of the page content. |
-
##: major headings -
###: subheadings -
####: as needed
Each page includes a table of contents (TOC) that lists all the H2-level (##) headings on the page.
This TOC appears in the right margin of the page and "floats" down the page as readers scroll.
Readers can click any heading in the floating TOC to jump to that section. The top-most heading currently displayed on the page is highlighted in the floating TOC.
To omit the floating TOC on a page (like the release notes page), add toc: false in the page's frontmatter.
Basic guides in the format "X with Y" where 'X' is a verb. This is the place where we tell users what they need to know before they get started. Guides should provide an easy introduction into the design/architecture/purpose of Sensu, along with a gentle introduction to features and terminology. Examples use sensuctl to cover the most common use cases.
Begin by explaining what is Y and the basic concepts associated with it.
## Reasons to use Y
When to use X / common use cases.
## Use Y to do X
Quick guide on how to create X, with one or two examples. Provide examples with sensuctl, and use flag parameters so users can copy/paste the examples.
Guides should not explain how to update/delete/list the given resource because that information is in the sensuctl reference guide.
## Next steps
Recommended reading around possible interactions of Y with other resources (e.g., checks and assets), further steps, etc.
The reference documentation is comprehensive and may seem dry compared to the guides. We use JSON objects (that are compatible with the sensuctl create command) to do in-depth explanations of each object type. We should also have a New and improved section that covers the difference between the same object in 1.x & 2.x.
## How X works
Explain in details how X works (e.g. Create events)
## X specification
In-depth explanations of each attribute
## X examples
Complete examples of X in JSON format
These templates originated with the Sensu 2.x documentation structure doc by Mercedes Coyle.
DO use code tags to indicate code samples and assign a syntax highlighter.
{{< code supported_language_name "Optional Display Name" >}}
Code example here
{{< /code >}}
DO separate commands from output using a description.
To see the systems monitored by Sensu:
{{< code shell >}}
sensuctl entity list
{{< /code >}}
You should see a list of monitored entities:
{{< code shell >}}
ID Class OS Subscriptions Last Seen
─────────────── ─────── ─────── ────────────────────── ───────────────────────────────
sensu2-centos agent linux entity:sensu2-centos 2018-10-25 02:12:16 +0000 UTC
{{< /code >}}
DON'T prepend the command prompt ($) unless the command is presented in the same block as its output. Better yet, introduce the output with a description.
DON'T include any indentation within code tags. This causes commands to fail when copy-pasted from the docs.
DO use comments within code samples to provide important context and enable scanning.
In code examples, use resource names that start with the resource type, followed by a hyphen and a short description: resource-desc.
For example, if your code example is for a CPU check, the resource name could be check-cpu. A Slack hander name in a code example might be handler-slack.
Use the language toggler to create a code sample with tabs for different languages or platforms.
{{< language-toggle >}}
{{< code shell "Tab 1" >}}
Hello, world!
{{< /code >}}
{{< code shell "Tab 2" >}}
Hello, world!
{{< /code >}}
{{< /language-toggle >}}
When providing code examples for resources and configurations, list the YAML example first, followed by the JSON example.
{{< language-toggle >}}
{{< code yml >}} type: CheckConfig api_version: core/v2 metadata: name: check-cpu namespace: production spec: check_hooks: null command: check-cpu.sh -w 75 -c 90 handlers:
- slack interval: 30 subscriptions:
- system timeout: 0 ttl: 0 {{< /code >}}
{{< code json >}} { "type": "CheckConfig", "api_version": "core/v2", "metadata": { "name": "check-cpu", "namespace": "production" }, "spec": { "check_hooks": null, "command": "check-cpu.sh -w 75 -c 90", "handlers": ["slack"], "interval": 30, "subscriptions": ["system"], "timeout": 0, "ttl": 0 } }{{< /code >}}
{{< /language-toggle >}}
Code samples labeled as {{< code json >}} must be valid JSON.
Use angle brackets for placeholders, and tell the reader what a placeholder represents.
To see the systems monitored by Sensu:
{{< code shell >}}
sensuctl entity <entity-name> info
{{< /code >}}
where `<entity-name>` is the name of one of your entities.
You can see any validation errors detected by the syntax highlighter when previewing the site locally.
Any red highlighting will also appear on the live site, so be sure to resolve any errors, by specifying text as the highlighter if you need to.
The Sensu docs also includes a python-based JSON validator that TravisCI runs when testing PRs.
Because it looks for code samples marked with {{< code json >}}, it's important that you only use that tag for valid JSON samples, otherwise use {{< code text >}}.
To see errors detected by the JSON validator, see the page for your pull request within TravisCI.
The Sensu docs use platforms blocks (example: {{< platformBlock "Ubuntu/Debian" >}}) to make it easier to represent multi-platform content.
To create multi-platform content, add platformContent = true and platforms = ["Platform Name 1", "Platform Name 2"] to the page frontmatter. This creates a platform-selector dropdown at the top of the page.
Then add platform tags to indicate platform content blocks.
For example:
{{< platformBlock "Linux" >}}
**Linux**
Linux-only step description
{{< code shell >}}
service sensu-agent restart
{{< /code >}}
{{< platformBlockClose >}}
{{< platformBlock "Windows" >}}
**Windows**
Windows-only step description.
{{< code shell >}}
sc restart sensu-agent
{{< /code >}}
{{< platformBlockClose >}}
By default, the site shows all platform blocks, so make sure to introduce each block with a heading.
The Sensu docs support four styles of callout: note, warning, pro tip, and important.
- Use a note to highlight a tip or a piece of information that may be helpful to know.
- Use a warning to indicate danger or a piece of information that is crucial to follow.
- Use a pro tip to point out ways to get the most out of Sensu's advanced features.
- Use an important callout to note major Sensu changes that users need to know about.
As of 5.18, the Sensu Go docs use Hugo shortcodes to format callouts.
{{% notice note %}}
**NOTE**: The `/auth/test` endpoint only tests user credentials created with Sensu's built-in [basic authentication provider](../../installation/auth#use-built-in-basic-authentication).
It does not test user credentials defined via an authentication provider like [Lightweight Directory Access Protocol (LDAP)](../../installation/auth#ldap-authentication) or [Active Directory (AD)](../../installation/auth/#ad-authentication).
{{% notice note %}}
Important things to know about shortcode formatting for callouts:
- The opening shortcode is different for each type of callout:
{{% notice note %}},{{% notice warning %}},{{% notice protip %}}, and{{% notice important %}}. - The closing shortcode is the same for all four types of callouts:
{{% notice note %}}. - The opening and closing shortcodes must be on a separate line from the text they encompass.
- Reference links do not work inside shortcodes. Instead, use inline links as shown in the example above.
- Other markdown formatting does work inside shortcodes (such as code tics and bold/italic face).
Before version 5.18, the Sensu Go docs use underscores to trigger JavaScript formatting for callouts. For example:
_NOTE: You can _still_ use **markdown** inside these callouts.
You can also use [reference links][1] in pre-5.18 callouts._
Use reference numbering for links except in shortcode-formatted callouts.
See the [installation guide][1].
# Link to the current version in the current section
[1]: ../overview
# Link to the current version in another section
[1]: ../../installation/overview
Use numbers to reference links. When adding new content, it is not necessary to renumber links so that they are referenced in order in the body of the text. In other words, it is OK to list [linked text][10] before [linked text][1] in the body of the text.
To link to the current version in the current section:
../overview
To link to the current version in another section:
../../installation/overview
To link to a specific version:
/sensu-go/5.15/installation/install-sensu
To link to the latest version in another product:
/sensu-core/latest/getting-started/versions
To link to a heading:
/sensu-core/latest/installation/install-sensu/#architecture-overview
Note: latest functionality doesn't work locally.
Steps within a list cannot contain empty lines. Empty lines within steps in an ordered list cause Hugo to lose track of the numbering.
For example:
1. Do a thing
{{< code shell >}}
shell command
{{< /code >}}
_NOTE: Note about this step._
2. Do another thing
{{< code shell >}}
shell command
{{< /code >}}
DO use — to create an em-dash rather than --.
DO use code style for filenames, directories, paths, commands, command line tools, field names, and field values.
DO use text style for Sensu resource names, concepts, and services.
DO write Markdown files with one sentence per line.
Exception: Use future or past tense if it is required to convey the correct meaning.
Exception: Use passive voice if active voice leads to an awkward construction.
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
Prefer English terms over Latin abbreviations. Use "for example" rather than "e.g." and "in other words" instead of "i.e."
Exception: Use "etc." for et cetera.
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
Avoid making promises (like "coming soon") or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
Avoid words like "currently" and "new." A feature that is new today might not be considered new in a few months.
This style guide is based on the excellent Kubernetes Documentation Style Guide and Anna MacLachlan's ever-helpful Sensu voice, tone, and style guide.