Skip to content

Home

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

Welcome! The Sensu documentation 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.

NOTE: The latest functionality doesn't work when you're running the docs locally. Replace latest with the decimal version of the Sensu docs you want to view when running the docs locally.

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.

Floating table of contents (right nav menu)

Each page includes a table of contents (TOC) that lists all the level 2 headings (##) on the page. This TOC appears in the right margin of the page and "floats" down the page as users scroll.

Users 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 front matter.

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.

Read Images and diagrams in the Sensu style guide for more information.

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