Skip to content

Sensu docs style guide

Jump to bottom
Hillary Fraley edited this page Apr 27, 2022 · 32 revisions

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 Goldmark 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.

Templates

See also the Sensu docs template.

Frontmatter

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.

Headings

Sensu Go guide template

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 for possible interactions of Y with other resources (e.g., checks and assets), further steps, etc.

Sensu Go reference template

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 detail 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.

Floating table of contents

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.

Guides and reference indexes

We use special shortcode files to automatically generate lists of guides and references on an index page in the Sensu Go docs: guidetypeListing and reftypeListing. This allows you to place guide and reference documents within any category and still include them in the pages listed in the Guides Index or Reference Index in the documentation.

The API overview also includes an automatically generated list of available APIs using the apitypeListing shortcode. The API shortcode uses frontmatter elements as well as dedicated CSS to create automatic columns.

These shortcodes rely on two frontmatter elements: $_title and type.

  • To list a page in the Guides Index, add the guide_title element and specify the title to use in the index. Add the type: "guide" element so that the shortcode can identify the page as a guide.
  • To list a page in the Reference Index, add the reference_title element and specify the title to use in the index. Add type: "reference" so that the shortcode can identify the page as a reference.
  • To list a page in the Available APIs, add the api_title element and specify the title to use in the list. Add type: "api" so that the shortcode can identify the page as a reference.

Code samples

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 responses/output in the description and by using the text shortcode for information that does not need to be copied.

To view a list of entities Sensu monitors:

{{< code shell >}}
sensuctl entity list
{{< /code >}}

The response should list the monitored entities:

{{< code text >}}
ID         Class    OS        Subscriptions                 Last Seen            
─────────────── ─────── ─────── ────────────────────── ─────────────────────────────── 
sensu2-centos   agent   linux   entity:sensu2-centos   2018-10-25 02:12:16 +0000 UTC  
{{< /code >}}

DON'T use the text shortcode {{< code text >}} for any other code examples except responses or output (code that does not need to be copied).

DON'T prepend the command prompt ($).

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.

Resource naming

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.

Language toggler

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 >}}

Resource definitions

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.

Include wrapped JSON examples where appropriate.

Use angle brackets for placeholders

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.

Validation

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 "JSON" >}}. To see errors detected by the JSON validator, see the page for your pull request within TravisCI.

Multi-platform content

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.

Callouts

The Sensu docs support four styles of callout: note, warning, pro tip, and commercial.

  • 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 a commercial callout to note documented commercial features.

Callout format for 5.18 and later versions

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 %}}
  • The opening shortcode is different for each type of callout: {{% notice note %}}, {{% notice warning %}}, {{% notice protip %}}, and {{% notice commercial %}}.
  • 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).

Callout format for Sensu Go pre-5.18 and Core, Enterprise, Enterprise Dashboard, and Uchiwa docs

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._

Links

Use reference numbering for links except in shortcode-formatted callouts.

In shortcode-formatted callouts, include the complete inline link:

For links in shortcode-formatted callouts, [use this link formatting](../../path-to-linked-page).

Link reference numbering

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

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.

Links and sections

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.

Lists

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 >}}
{{% notice note %}}
**NOTE**: Note about this step.
{{% /notice %}}

2. Do another thing
{{< code shell >}}
shell command
{{< /code >}}

Formatting

DO use &mdash; 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.

Writing style

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.

Use present tense

Exception: Use future or past tense if it is required to convey the correct meaning.

Use active voice

Exception: Use passive voice if active voice leads to an awkward construction.

Use clear and obvious language

Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."

Address the reader as "you"

Avoid Latin phrases

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.

Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.

Avoid statements about the future

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 or beta information.

Avoid statements that will soon be out of date

Avoid words like "currently" and "new." A feature that is new today might not be considered new in a few months.

Acknowledgements

This style guide is based on the excellent Kubernetes Documentation Style Guide and Anna MacLachlan's ever-helpful Sensu voice, tone, and style guide.

Clone this wiki locally