Skip to content

Home

Jump to bottom
Hillary Fraley edited this page Nov 22, 2022 · 95 revisions

Sensu Documentation Wiki

Welcome! This wiki is a resource for those who write and maintain the Sensu documentation.

Overview

The official Sensu docs are stored at https://github.com/sensu/sensu-docs and published at https://docs.sensu.io/.

Other Sensu resources and GitHub repos are relevant to the docs and include helpful information:

Find all of Sensu's GitHub repositories at https://github.com/sensu.

Organization

The docs site is organized by product, version, and section.

# URL structure
https://docs.sensu.io/{ product name }/{ version number }/{ section name }/{ subsection name }/{ page name }

# Examples
https://docs.sensu.io/sensu-go/6.9/api/overview
https://docs.sensu.io/sensu-go/6.9/observability-pipeline/observe-events/events/

The current docs version number is aliased as latest. For example, if the current Sensu version is 6.10, the URLs for pages in the 6.10 docs set will be:

# URL structure
https://docs.sensu.io/{ product name }/latest/{ section name }/{ subsection name }/{ page name }

# Examples
https://docs.sensu.io/sensu-go/latest/api/overview
https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-events/events/

Docs landing page

Docs site configuration

The file https://github.com/sensu/sensu-docs/blob/master/config.toml controls the product and version information at the top of each page. config.toml also includes the docs site Google Analytics info and other site configuration details.

Products

The Sensu Go documentation for https://github.com/sensu/sensu-go and https://github.com/sensu/sensu-enterprise-go is our active product.

Plugins documentation was originally created as a companion to the Sensu Plugins organization. Plugins content was ported over from http://sensu-plugins.io/ in mid-2018. The plugins docs were updated for Sensu Go in early 2021 and moved into the plugins category in the Sensu Go docs.

These products have reached end-of-life or have otherwise been deprecated:

Product names are defined in a few key locations: config.toml, static.json, footer.js.

The Platforms and distributions page lists the versions of RHEL, Debian, Ubuntu, and Windows with supported commercial distributions. Users can search packagecloud for supported commercial distributions for other platforms.

Versions

Within each product, docs are versioned through 100% duplication: for every version of each product, one folder contains all the docs.

The system of 100% duplication was designed for a release system with a relatively slow progression of minor versions. With the higher rate of minor version releases in Sensu Go, docs are published for only supported versions (current version + three previous minor versions.

Updates

Update the current version and all versions supported under the Sensu License (current version + three previous minor versions), plus any pre-release versions currently published on the docs site.

Add a version

Read Add a docs version in this wiki for more information.

Latest

The docs project include a feature to serve the latest version of a given doc by substituting latest for the version number in the URL. For example docs.sensu.io/sensu-go/latest/guides always takes you to the latest version of that page. The version alert bar also works using this feature.

The latest redirect feature is configured in static.json, which must be manually updated to list the latest version of each product to use in the redirect.

Version alert

The version alert bar appears if you're viewing a version other than the latest. Clicking the version alert bar takes you to the latest version of the page. The version alert bar can be dismissed, but the dismissed state does not persist when navigating to other pages.

Version dropdown

Users can switch versions using the dropdown at the top of each page. Because the version dropdown is available on every page, it can create broken links for pages that don't exist in previous versions.

Sections

Within a product and version, individual docs can live at the root level or within a section. Sections are surfaced in the sidebar. Sections require an _index.md file within the section directory.

Sensu Go sections:

  • Sensu Go (top level page)
  • Release notes (top level page)
  • Get Started with Sensu (top level page)
  • Platforms and Distributions (top level page)
  • Commercial Features (top level page)
  • Supported Versions (top level page)
  • Sensu Plus (top level page)
  • Observability Pipeline (section with one level of subsections)
  • Operations (section with one level of subsections)
  • Guides Index (index listing of all docs pages with type: "guide" in the front matter)
  • Sensuctl CLI (section)
  • Web UI (section)
  • Sensu Catalog (section)
  • API (section with one level of subsections)
  • Reference Index (index listing of all docs pages with type: "reference" in the front matter
  • Plugins (section)
  • Learn Sensu (section)

Pages

Docs are written as markdown files with extension .md. Read the style guide for style details.

Redirects

To redirect a URL, use static.json to apply redirects using URL matching.

Images and diagrams

Images are not stored with content within the docs project. Images are stored at /static/images.

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

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.

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

Template

Refer to the Sensu docs template and the Templates section in the Sensu docs style guide for template guidelines and requirements.

User research

Search

The Sensu docs use Algolia DocSearch configured in the footer_js partial. Log in at algolia.com with the Reliability team credentials stored in 1Password to see search analytics.

Search results should be scoped to the currently viewed product and version. Searches from the docs home page should be scoped to the latest version of all products.

Sensu Go live demo

About Sensu

Sensu Go source code

See the Sensupedia for source code references.

Sensu Go product dimensions

service
	agent
	backend
	sensuctl
platform
	generic linux
	specific linux
	windows
	macOS
artifact
	binary
	package
	Docker image
	Build from source
use case
	containers
	bare metal
	VM
	config management
support level
	supported
	available
	not supported
tier
	OSS (engine)
	free
	licensed

Design ideas

Tabs

Include tabs along the bottom of the header. When selected, the tabs should cause a unique sidebar to display. Individual pages should be assigned to a tab using a frontmatter attribute. Implementation of tabs should not require changes to page URLs.

Design reference: https://developers.nest.com/guides/get-started (Get Started, API Guides, Account Management, Samples tabs)

Sensuctl docs design

A slot-machine style command builder that produces docs for different combinations.

Reference docs design:

An expandable, contractable config template with built in docs, possibly using the data used for the dashboard form generator.

Design references:

API docs

API docs should be re-organized by task, expanded to include attribute details, expanded to include guides to get started and accomplish common tasks, and integrated with automated testing.

References:

Branding

History

The Sensu docs were originally part of the sensu/website project. They moved to a standalone Hugo site and launched in March 2018.

Clone this wiki locally