-
Notifications
You must be signed in to change notification settings - Fork 56
Sensu docs style guide
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.
See the Sensu docs template.
All content pages must start with a front matter section. Read Hugo front matter for details.
-
##: major headings (will appear in floating table of contents) -
###: subheadings -
####and#####: as needed
Do not use level 1 headings (#).
Include complete code examples that are ready to use whenever possible.
Use code tags to indicate code samples and assign a syntax highlighter:
{{< code supported_language_name "Optional Display Name" >}}
Code example here
{{< /code >}}
Separate command examples from responses and 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 >}}
Use comments within code samples to provide important context and enable scanning.
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.
Review the Sensu doc template for more format examples for code examples.
In code examples, use resource names that start with the resource type, followed by a hyphen or underscore 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 toggle 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 >}}
For Sensu resource examples, use the language-toggle shortcode to provide both a YAML- and JSON-format example.
In 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.
If a command requires user-provided information, use angle brackets for placeholders in the example (like <ENTITY_NAME>). Tell users what the placeholder represents and to replace the placeholder before running the example.
To get more information about a specific entity, run the following command. Replace <ENTITY_NAME> with the name of the entity you want more information about:
{{< code shell >}}
sensuctl entity <ENTITY_NAME> info
{{< /code >}}
You can see any validation errors detected by the syntax highlighter when you preview 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 repo also includes a python-based JSON validator that Travis CI runs when testing PRs.
Because the validator looks for code samples marked with {{< code json >}}, use the json syntax only for valid JSON samples. Otherwise use {{< code shell "JSON" >}}.
Images are stored at /static/images instead of in the /content directory.
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.
Inside the /static/images director, store images within subdirectories for the product name and page name.
The product names are:
coreenterpriseenterprise_dashboardgouchiwa
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.
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.
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 -->
Use color #b71e11 for screenshot callouts like arrows and boxes.
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 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.
Reference documentation describes Sensu resources. Start each reference with a paragraph that describes the purpose of the resource.
The first section in a reference should be a representative example of the resource in YAML and JSON formats. Include a text explanation of any information required to understand the example.
Subsequent sections in references should describe Sensu concepts related to the resource and configuration considerations for the resource, such as the purposes of certain resource attributes and options that users will configure according to their needs. For example, the checks reference describes how to interpret check results, check scheduling, special cases like proxy checks, the purpose and use of the round robin and subdue attributes, and check-related concepts like token substitution and hooks.
Resource references must include a specification that describes each attribute in the resource definition. Specifications are divided into hierarchical subsections, starting with top-level attributes like name, metadata, and spec, and followed by subsections of attributes organized the same way they appear in the resource definition. Review the check specification for an example.
At the end of the reference, add more resource definition examples if appropriate. For example, the silencing reference includes a number of examples after the specification.
Special shortcode files automatically generate the 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 front matter elements: $_title and type.
- To list a page in the Guides Index, add the
guide_titleelement and specify the title to use in the index. Add thetype: "guide"element so that the shortcode can identify the page as a guide. - To list a page in the Reference Index, add the
reference_titleelement and specify the title to use in the index. Addtype: "reference"so that the shortcode can identify the page as a reference. - To list a page in the Available APIs, add the
api_titleelement and specify the title to use in the list. Addtype: "api"so that the shortcode can identify the page as a reference.
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 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.
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).
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. Link references should be listed at the bottom of the Markdown file.
See the [installation guide][1].
# Link in list at the bottom of the page
[1]: ../install-sensu/
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.
In shortcode-formatted callouts, include the complete inline link:
For links in shortcode-formatted callouts, [use this link formatting](../../path-to-linked-page).
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
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 >}}
Use — to create an em-dash rather than --.
Use code style for file names, directories, paths, and commands. Do not use code style for attribute names and values.
Use text style for Sensu resource names, concepts, and services.
Write Markdown files with one sentence per line. To create a paragraph break, add a second line break.
This is an example to show how to handle line breaks in a Sensu content file.
This is the second sentence of the first paragraph.
This is the third sentence.
On the docs site, these sentences will appear as a single paragraph.
This sentence begins a second paragraph in the same content file.
I pressed return twice to start a new paragraph.
| 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. |
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 unnecessary phrases, such as "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 improve the docs for all users.
Avoid making promises (like "coming soon"), giving hints about the future, or using phrases that suggest a different future state (like "currently"). If you need to talk about an alpha feature, put the text under a heading that identifies the feature as such. For example:
{{% notice note %}}
**NOTE**: The Sensu Catalog is in public preview and is subject to change.
{{% /notice %}}
Or:
{{% notice note %}}
**NOTE**: The catalog-api tool is an alpha feature and may include breaking changes.
{{% /notice %}}
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.