Skip to content

Home

Jump to bottom
Hillary Fraley edited this page Aug 26, 2021 · 95 revisions

Sensu docs wiki

Welcome! This wiki is a resource for maintainers of the Sensu docs.

Overview

Sensu docs live primarily at docs.sensu.io, but they also include information stored elsewhere:

Organization

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

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

# Example
https://docs.sensu.io/sensu-go/5.11/api/overview

Home page

Products

Product names are defined in a few key locations: config.toml, static/stylesheets/homepage.css, static.json, footer.js. See this PR as a reference for creating new products or changing product names.

Versions

Within each product, docs are versioned through 100% duplication, which means that for every version of each product, we have a folder containing all the docs.

Versioned products:

  • Sensu Go (starts at 5.0)
  • Sensu Core
  • Sensu Enteprise (starts at 2.6)
  • Sensu Enteprise Dashboard (starts at 2.9)

Non-versioned products:

  • Uchiwa: Although the Uchiwa project is versioned, historically the docs have always lived at /uchiwa/1.0.

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; selecting it takes you to the latest version of the page. It can be dismissed, but the dismissed state does not persist when navigating to other pages.

Version dropdown

Users can switch versions using the dropdown. 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 (example).

Sensu Go sections:

  • Sensu Go (top level)
  • Release notes (top level)
  • Get Started with Sensu (top level)
  • Platforms and Distributions (top level)
  • Commercial Features (top level)
  • Supported Versions (top level)
  • Observability Pipeline
  • Operations
  • Guides Index
  • Sensuctl CLI
  • Web UI
  • API
  • Reference Index
  • Plugins
  • Learn Sensu

Pages

Docs are written as markdown files with extension .md. See the style guide.

Redirects

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

Images and diagrams

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

Files have the option to be versioned or not. To create a versioned file, add the file to a /files directory within the version directory (example). To create a not versioned file, add the file to /static/files.

# Reference an image in /static/images
<div style="text-align:center">
<img alt="Sensu Clustered Architecture" title="Clustered Sensu Go Backend with Embedded etcd." src="/images/clustered_architecture.svg" width="800 px">
</div>
<!-- Diagram source: https://www.lucidchart.com/documents/edit/475f950e-2770-4bf7-af73-57bc834cebdd -->

# Reference a file in a versioned /files directory
See the [example config file](../../files/agent.yml) for flags and defaults.

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.

Audience

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 get started content

About Sensu

Sensu Go source code

See the Sensupedia for source code references for future automation.

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