-
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". | Use passive voice. |
Code samples
{{< highlight shell >}}
sensuctl entity list
{{< /highlight >}}
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
Tables
heading | heading
--------|------
text | text
text | text
Multi-platform content
{{< platformBlock "Linux" >}}
**Linux**
Linux-only step description
{{< platformBlockClose >}}
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"]
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 |
-
##: major headings -
###: subheadings -
####: as needed
Basic guides in the format How to X with Y. This is the place where we tell users what they need to know before they even get started. They should provide an easy introduction into the design/architecture/purpose of Sensu, along with a gentle introduction to features and terminology. Examples use sensuctl in order to cover the most common use cases.
## What are Sensu X?
Explain what is X and the basic concepts associated to it.
## Why use X?
When to use X / common use cases.
## Using z to do Y
Quick guide on how to create X, with maybe one or two examples max. We should provide examples with sensuctl that uses flag parameters so users can copy/paste them.
We don’t need to explain how to update/delete/list the given resource, that would be the job of the sensuctl reference guide.
## Next steps
Recommended reading around possible interactions of X with other resources (e.g. checks & assets), further steps, etc.
The reference documentation is comprehensive and pretty dry compared to the overview guides. We use JSON objects (that are compatible with the sensuctl create command) in order 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 do X work?
Explain in details how X works (e.g. How are events created?)
## New and improved X
Cover the difference between X in Sensu 1 & Sensu 2
## 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 highlight tags to indicate code samples and assign a syntax highlighter.
DO separate commands from output using a description.
To see the systems monitored by Sensu:
{{< highlight shell >}}
sensuctl entity list
{{< /highlight >}}
You should see a list of monitored entities:
{{< highlight shell >}}
ID Class OS Subscriptions Last Seen
─────────────── ─────── ─────── ────────────────────── ───────────────────────────────
sensu2-centos agent linux entity:sensu2-centos 2018-10-25 02:12:16 +0000 UTC
{{< /highlight >}}
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 highlight 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.
Use the language toggler to create a code sample with tabs for difference languages or platforms.
{{< language-toggle >}}
{{< highlight "Tab 1" >}}
Hello, world!
{{< /highlight >}}
{{< highlight "Tab 2" >}}
Hello, world!
{{< /highlight >}}
{{< /language-toggle >}}
Code samples labelled as {{< highlight 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:
{{< highlight shell >}}
sensuctl entity <entity-name> info
{{< /highlight >}}
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 {{< highlight json >}}, it's important that you only use that tag for valid JSON samples, otherwise use {{< highlight 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**
{{< highlight shell >}}
service sensu-agent restart
{{< /highlight >}}
{{< platformBlockClose >}}
{{< platformBlock "Windows" >}}
**Windows**
{{< highlight shell >}}
sc restart sensu-agent
{{< /highlight >}}
{{< platformBlockClose >}}
By default, the site shows all platform blocks, so make sure to introduce each block with a heading.
The Sensu docs support three styles of callout: note, warning, and pro tip.
Use a note to highlight a tip or a piece of information that may be helpful to know.
For example:
_NOTE: You can _still_ use Markdown inside these callouts._
Use a warning to indicate danger or a piece of information that is crucial to follow.
For example:
_WARNING: This feature requires the latest version of Sensu._
Use a pro tip to point out ways to get the most out of Sensu's advanced features.
For example:
_PRO TIP: You can override integration attributes on a per-contact basis using contact routing._
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-core/1.4/installation/overview
To link to the latest version in another product:
/sensu-core/latest/overview/architecture
To link to a heading:
/sensu-core/latest/overview/architecture/#architectural-diagram
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
{{< highlight shell >}}
shell command
{{< /highlight >}}
_NOTE: Note about this step._
2. Do another thing
{{< highlight shell >}}
shell command
{{< /highlight >}}
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.
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 style guide.