Skip to content

Documentation and communication processes

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

Create /sensu-docs PRs

  1. Clone the sensu-docs repo locally (follow the readme instructions).
  2. Create a new local branch: git checkout -b BRANCH_NAME.
  3. Use any text editor to make local changes in the /sensu-docs files.
  4. Run yarn and yarn run server to view and test local updates in the browser at http://localhost:1313/. Make sure to run your changes locally to confirm that the updated page is formatted correctly.
  5. When satisfied with the changes, use git commands to add, commit, and push your changes.
  6. In the /sensu-docs repo, create a pull request for your changes.

If you are changing content that affects more than one version of the Sensu docs, commit your changes to a single docs version to make the PR easier to review and feedback easier to incorporate. For example, if your change applies to Sensu Go versions 6.7 and 6.8, start by making the changes only in the 6.8 doc. After the PR is reviewed and approved, copy the changes to the 6.7 doc and commit again before merging the PR.

Prepend [WIP] to PR titles to indicate that you're still working and the PR isn’t ready for review. Remove [WIP] when the PR is ready for review. Use the in progress, content review ready, and ready for review GitHub labels to indicate PR status.

PR reviews for /sensu-docs

After you create a new PR in the /sensu-docs repo, follow these steps

  1. Add a reviewer for the /sensu-docs PR. The reviewer should usually be the person who opened the relevant docs issue or identified the problem your PR addresses. If the PR is new feature documentation, the reviewer should be the person who worked on the relevant PR in /sensu-go or /sensu-enterprise-go. Some PRs require multiple reviewers. If you are not sure who should review a PR, ask in #sensu-customer or #sensu-engineering.
  2. Wait about 24 hours for PR review. Send a Slack message to the reviewer if time constraints prevent waiting or if the review is not completed within a day or two.
  3. Incorporate reviewer comments and request final review/approval if appropriate.
  4. After the PR is approved, propagate the changes to additional docs versions if appropriate.
  5. Merge the PR (if the changes are specific to a patch release, hold the changes for the release). Merged PRs are automatically published to https://docs.sensu.io.

For some types of PRs, it's OK to merge without a review. Examples include fixing typos and incorrect links and minor rewording for clarification.

If you are reviewing a docs PR, make sure to run the site locally to confirm there are no formatting errors and test any commands and code samples. Use the GitHub review/comment feature to add feedback and request changes. If you request changes, re-review and approve after the changes are made.

For community contributions, do not ask contributors to propagate changes to all versions. If they haven’t done it, either push to their branch or open a separate PR. Do merge community-contributed PRs instead of asking the contributor to merge.

New docs process

The process for creating new documentation is roughly as follows:

Awareness

  • Read issues and pull requests (PRs) for sensu-go and sensu-enterprise-go via email alerts for both repos.
  • Read posts in the #sensu-engineering and #sensu-product channels to maintain general awareness.
  • Save any emails and links to Engineering planning docs, sensu.io blog posts, and Slack conversations as well as any other information that might be helpful when it’s time to write docs.

Monitoring

  • Review the release milestones for sensu-go and sensu-enterprise-go every week or two to get some idea of what’s going to be in which release.
  • Create docs issues for features and changes that will need documentation, even if they aren’t far enough along to start on the docs. Sometimes, the Sensu engineers may create docs issues themselves. Save helpful information and links in the docs issue: the sensu-go/sensu-enterprise-go issue/PR, saved emails, links to the affected code, links to Slack discussions, etc.
  • Tag release-related docs issues with the relevant release milestone from sensu-go/sensu-enterprise-go. Docs issues with a release milestone are displayed on the Engineering release planning board, which is helpful see there are outstanding docs tasks for a rele

Documenting

When a major or minor release approaches, start working on the documentation. It's not always clear exactly when a release will happen, and the docs work is more extensive for some features than others, so the right time to start docs is a matter of guessing when the release might happen, understanding which features are "done" (merged), and thinking through how much time it will take to write the docs. Docs should be underway within a couple weeks of a new release.

For major and minor releases, the first docs task for a new release is to create a new docs version. Sensu docs versions correspond to Sensu major or minor versions. For example, for a Sensu Go 6.8.0 release, create the 6.8 docs. All 6.8.x patch releases are covered by the 6.8 docs (in other words, patch releases do not require a new docs version).

When the new docs version is published, write the feature docs. Use the Sensu Go LTS skunkworks scenario to test new features before a release.

NOTE: The sensu-go/sensu-enterprise-go PRs must be merged to the develop/6 branch to be available in the Sensu Go LTS skunkworks scenario. Also, when a new major version of Sensu is released (i.e. 7.0), the docker-compose.yaml file must be updated to use the correct images in place of sensu/sensu-ci:develop_6-develop_6-alpine and sensu/sensu-ci:develop_6-develop_6-rhel7.

For questions while writing docs, contact the Sensu engineer who worked on the relevant sensu-go/sensu-enterprise-go PR or ask in the #sensu-engineering Slack channel.

When the doc draft is ready for review, create a sensu-docs PR and request review from the engineer who worked on the relevant sensu-go/sensu-enterprise-go PR. If feedback requires major changes, consider requesting a final review after incorporating the feedback.

For major and minor versions, merge the docs PRs as soon as they are approved. Before the release actually happens, the new doc version is a “pre-release” doc set that is not marked as latest.

Patch releases should not have changes, although they sometimes do. If a patch release requires a change or update in the docs, hold the docs PR for that change until the actual release.

Helpful Sumo Logic Slack channels

Channel Description
#sensu-engineering Sensu team's engineering channel. Find discussions about new features and product changes and ask questions.
#sensu-customer Sensu team's customer engineering channel. Find discussions about customer issues and existing features and ask questions.
#sensu-releases Sensu team's release planning, preparation, and discussion channel. Find discussions about specific releases among those completing the release tasks.
#sensu-developer-advocacy Sensu team's developer advocacy channel. Find discussions about customer requests and ask questions.
#sensu-product Sensu team's product channel. Nov 2022 note: currently not very active; Sensu product manager position remains open.

Information sources

Source Description
/sensu-go Code repository for Sensu Go. Does not include commercial features.
/sensu-enterprise-go Code repository for commercial features in Sensu Go.
/skunkworks Docker and virtual machine scenarios for running Sensu Go. The sensu-go-lts scenario is useful for documenting unreleased new features. The sensu-go-standalone scenario is useful for testing existing features.
Bonsai The Sensu asset index. Includes readmes for all Sensu plugins, with links to the GitHub repos for individual plugins.
/sensu-go-workshop Code repository for the Sensu Go workshop. View companion videos in the Sensu Go Workshop channel on YouTube.
/catalog Code repository for Sensu Catalog integrations.
/catalog-api Code repository for the catalog-api tool for testing integrations and creating a private catalog.
Caviar demo Live demo of the Sensu web UI. Log-in credentials are in 1Password.
Sensu blog Blog posts by Sensu developer advocates and customers about various Sensu features.
Sensu YouTube channel Videos, webinars, and workshop lessons.
/monitoring-caviar Code repository for the Caviar project. Readme includes instructions for the Caviar steps in the release process.

Sources for upcoming releases

Information sources for upcoming releases:

Customer communication

We communicate documentation changes to customers with posts to the Sensu Docs category of the Sensu Community Forum on Discourse.

After each release, we publish a "docs digest" that briefly summarizes the release contents, links to all documentation that was added or updated based on the release, and a link to the release notes. See the docs digest for Sensu Go 6.9.0 as an example.

When we publish a new page of documentation or make substantial updates to a document unrelated to a release, we make a special post to notify the Sensu community. See the message about new PostgreSQL docs as an example.

After making a post on Discourse, add a message in the #documentation channel of the Sensu Community Slack to help customers find it.

Clone this wiki locally