Skip to content

Home

Jump to bottom
Hillary Fraley edited this page Nov 21, 2019 · 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.
  • Plugins: Since this content isn't tied to a single codebase, all plugins content lives at /plugins/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, we're working on a way to reduce the overall content surface area by deprecating outdated versions of the docs. (See Trello and https://github.com/sensu/sensu-docs/issues/1647.) It might also be prudent to consider changing to a partially-versioned system or a deploy-a-branch pattern using a tool like Netlify (reference).

Which versions do I need to update?

  • For usability and consistency updates, at a minimum, update the current version and any pre-releases versions. Bonus points for updating all versions supported under the Sensu License (current version + three previous minor versions).
  • For undocumented features, update all versions.
  • For important security-related updates, update all versions.

Remember: find-and-replace is your friend!

How do I add a version?

See this wiki page.

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 include a homepage with an automatically generated list of pages. For example: https://docs.sensu.io/sensu-core/1.8/api. Sections require an _index.md file within the section directory (example).

Sensu Go sections:

  • Landing Page (top level)
  • Release notes (top level)
  • Getting Started
  • Installation
  • Guides
  • Dashboard
  • API
  • Sensuctl
  • Reference

Pages

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

Redirects

To redirect a URL, use Hugo's aliases frontmatter attribute. You can also use static.json to apply redirects using URL matching.

Images and diagrams

Images are not versioned within the docs project. Images live 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 lives in Lucidchart. Diagrams are clearest and smallest when uploaded as SVGs with transparent backgrounds; screenshots and diagrams using non-SVG logos are best uploaded as PNGs.

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.

Create an offline PDF copy of docs

Follow these steps to create an offline PDF copy of a version of the docs:

  1. Clone a local copy of the docs repo, /sensu-docs.
  2. Run a local hugo server with offline layouts:
yarn
yarn run server --layoutDir=offline
  1. Delete the versions.md file from your local copy of the docs version you want to PDF.
  2. Navigate to http://localhost:1313/ and select the product and version you want to PDF. Copy the local URL.
  3. Open Acrobat and navigate to File → Create → PDF from Web Page to open the Create PDF from Web Page window.
  4. Paste the local URL in the URL: field.
  5. Click Capture Multiple Levels and select the following Settings options:
  • Leave Get only ... level(s) selected and change the number of levels to 10.
  • Select Stay on same path and Stay on same server.
  1. Click the Settings... button to open the Web Page Conversion Settings window. Make sure the File type is HTML. Under PDF Settings, select only Create bookmarks.
  2. In the Web Page Conversion Settings window, click OK.
  3. In the Create PDF from Web Page window, click Create.
  4. When the PDF is generated, save the file with this naming convention: sensu-go-5-12_sensu-docs
  5. Save the PDF in Sensu's Amazon S3 account in the sensu-docs bucket, inside the pdfs folder.

Update the Supported Versions page (versions.md)

Update the supported versions page (versions.md) each time we release a minor version of Sensu Go. This requires making one addition and one revision to versions.md:

  • Add a row in the versions.md table for the new minor version. Update the link to the release notes and the offline PDF copy in AWS.
  • Mark the fourth previous version as "Not supported" in the versions.md table. For example, if you add version 5.15, mark version 5.12 as "Not supported."

Archive docs versions

Remove docs that are more than three minor versions old from the docs.sensu.io website. Here's how to remove the archived version of the docs from docs.sensu.io:

  1. Create the archived and product directory. Run:

    mkdir -p archived/sensu-go

  2. Use git to move the target version into the archive:

    git mv content/sensu-go/5.0/ archived/sensu-go/

  3. Edit config.toml to remove the version being archived:

    vi config.toml

  4. Commit changes to the sensu-docs repo and create a pull request.

Create offline PDF of an archived version

  1. Clone a local copy of the docs repo, /sensu-docs.

  2. Symlink the archived version into the live site content for local server usage.

    a. Change working directory to the product root:

    cd content/sensu-go

    b. Create a relative symlink to the archived doc content:

    ln -sfv ../../archived/sensu-go/5.0

  3. Run yarn and yarn run server --layoutDir=offline

  4. Open http://localhost:1313/sensu-go/5.0/ and create the offline PDF.

Issue cleanup

Before starting issue cleanup (when you expect to close or update issues in bulk), run the following command in the #reliability Slack channel to pause alerts:

/github unsubscribe sensu/sensu-docs

When finished, restart with:

/github subscribe sensu/sensu-docs

Sensu Go getting started content

The Sensu monitoring-event-pipeline workflow can be summarized as follows:

  1. Create events using the events API
  2. Handle API-created events
  3. Add an agent and create a check to collect metrics

See the Katacoda wiki page.

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)

Third column for table of contents

Make the center column more narrow to support a right-side column for a fixed table of contents The table of contents should be a fixed element that persists on scroll. As I scroll through the page, the table of contents highlights the line representing the currently viewed section. Ideally we would have the option for autogenerated or custom table of contents, configured via a frontmatter attribute.

Design references:

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