Skip to content

Sensu docs style guide

Jump to bottom
Hillary Fraley edited this page Nov 23, 2022 · 32 revisions

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 the Sensu docs template.

Front matter

All content pages must start with a front matter section. Read Hugo front matter for details.

Headings

Do not use level 1 headings (#).

Code examples

Include complete code examples that are ready to use whenever possible. If a command requires user-provided information, use placeholders (like <ENTITY_NAME>) in the example and instruct users to replace the placeholder in the text that introduces the example.

For Sensu resource examples, use the language-toggle shortcode to provide both a YAML- and JSON-format example.

Review the Sensu doc template for format examples for code examples.

Images and diagrams

Images are stored at /static/images instead of in the /content directory.

Image file naming

Use image names that briefly describe what the image shows. Use underscores (not hyphens) in file names.

For example:

namespace_switcher.png

If you need to create a versioned image, add the Sensu version to the image filename. For example: confirm_proxy_entity_690.

Image directory naming

Inside the /static/images director, store images within subdirectories for the product name and page name.

The product names are:

  • core
  • enterprise
  • enterprise_dashboard
  • go
  • uchiwa

Name the page subdirectory after the page name in the URL.

For example, the subdirectory name for View and manage resources in the web UI, whose page name in the URL is view-manage-resources, is view_manage_resources. The correct subdirectory structure for an image in View and manage resources in the web UI is /static/images/go/view_manage_resources.

Image optimization and compression

To conserve space in the Heroku slug, use ImageMagick to optimize and compress every GIF and PNG before you reference it in the docs.

Use these ImageMagick commands:

  • For every still png image: magick mogrify -layers 'optimize' <PNG_NAME>.png
  • For every animated gif image: magick mogrify -layers 'optimize' -fuzz 3% <GIF_NAME>.gif

For images that are used only in an archived docs page, move the images in that version to the archived_version_images directory. The archived image directory is listed in the .slugignore file and therefore does not count toward the slug size.

Reference images in text

To display an image in the text, add an image reference where you want the image to appear on the page.

If the image is saved in /static/images, use the following reference format:

{{< figure src="/images/go/bsm_module/create_service_670.gif" alt="Add a new business service with the web UI module" link="/images/go/bsm_module/create_service_670.gif" target="_blank" >}}

If the image was created in Lucidchart, add the source link on the line immediately following the image reference:

<!-- Diagram source: https://www.lucidchart.com/documents/edit/475f950e-2770-4bf7-af73-57bc834cebdd -->

Screenshot callouts

Use color #b71e11 for screenshot callouts like arrows and boxes.

Diagrams

The Sensu diagram template is available in Lucidchart. Diagrams are clearest and smallest when uploaded as SVGs with transparent backgrounds, but images must be saved as PNGs so that docs can be converted to PDF for offline access (PDF does not display SVGs).

Guides

Guides tell users how to achieve something with Sensu. Guides should provide simplified information about the design, architecture, and purpose of Sensu, along with a gentle introduction to features and terminology. Use sensuctl in examples to cover the most common use cases.

Begin each guide by explaining the task and the basic Sensu concepts associated with it. For example, a guide about collecting metrics might explain checks, metrics, and events in the introduction.

The first subsection in each guide should describe requirements for completing the guide. A standard set of requirements is a running Sensu backend and at least one agent, plus sensuctl configured as the admin user. Some guides add on to Sensu resources created in other guides, for example adding a handler for a check created previously. In these cases, the check the guide relies on should be listed as a requirement, along with a link to the guide that explains how to create the check.

Example commands should be ready to use when possible, with placeholders for user-provided information.

Minimize or eliminate links in the body (instructions) of a guide. Guides are intended to help users achieve the task as directly as possible and links in the midst of the instructions can be a distraction. Instead, list links at the end in the What's next section.

The last section in a guide should be What's next, a collection of explanations and links to other documentation. This section might include possible next steps ("Now that you've created a check, add a pipeline to send check results to email") and links to more information about the Sensu concepts and assets used in the guide. Give users a next step to continue exploring and learning about Sensu.

References

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