Skip to content

Instantly share code, notes, and snippets.

@apaskulin

apaskulin/sensu-q1.md

Last active May 21, 2018 23:56
Show Gist options
  • Save apaskulin/417b95781b37bbcf8b95da75aa682e8a to your computer and use it in GitHub Desktop.
Save apaskulin/417b95781b37bbcf8b95da75aa682e8a to your computer and use it in GitHub Desktop.
Download ZIP
Sensu Docs: Information Review
Raw
sensu-q1.md

Sensu Docs: Information Review

Based on Sensu Core docs version 1.3
April 25, 2018

sensu-logo

Guiding Principles

  • Provide a clearer path to the "Hello World" moment for new users.
  • Remain easily navigable by experienced Sensu users who have some idea what they're looking for.

Highlights

  • Content is thorough and thoughtful. Great quick start, guides, and reference docs. 🌟
  • Empathetic, understanding-focused tone helps users in moments of confusion or complexity.
  • "Edit this page" button reduces friction for contributors.
  • Front page navigation style is mobile-friendly and reduces cognitive overhead.
  • Great cross-referencing between installation guides and platform pages.
  • "You're viewing documentation for an older or pre-release version" alert bar supports users entering the docs from a search engine.

Information Architecture

Existing

Two-level, universal sidebar navigation

  • Sensu Core
    • CHANGELOG
    • FAQs
  • API
  • Guides
  • Installation
  • Overview
  • Platforms
  • Quick Start
  • Reference

In this architecture, each section carries equal weight. This strategy has the advantage of being easy to maintain and, importantly, easy for users to understand.

Ideal

Tabbed navigation with two-level, section-specific sidebar menu

  • Guides (tab)
    • Sensu Core (landing page)
    • Quick Start
    • Overview
    • Guides
    • FAQs
  • Installation (tab)
    • Installation
    • Configuration
    • Upgrading
  • Reference (tab)
    • API
    • Platforms
    • Reference
    • CHANGELOG

This architecture organizes content into larger categories based on user needs:

  • The Guides tab absorbs everything helpful to new users: content focused on learning and understanding.
  • For experienced users, the Reference section provides detailed reference and platform-specific information.
  • As one of the more complex steps in the process, Installation gets its own tab.

Users can switch between tabs and choose individual pages from the sidebar. This organization eliminates expandable menus and provides tailored portals for new and experienced users.

Top To-Dos

1. Use the product landing page to guide new users

The landing page should give users a sense of what Sensu Core can do and where they should go next. I'd like to add:

  • Brief introductory content, borrowed in this mockup from "What is Sensu"
  • A friendly, high-level architecture diagram
  • Links to Quick Start content, especially the awesome "Learn Sensu in 15 Minutes", styled as buttons
  • Links to most popular pages based on Google Analytics, styled as buttons

This content will help both new and experienced users jump directly to the information they need.

Rough mockup:

landing page mockup

2. Replace architecture diagram

Update the current architecture diagram so it's easier to see on a laptop and uses the Sensu brand colors. To improve accessibility, I recommend removing the animation, or at least having the animation off by default.

3. Complete and debug quick start guides

The Quick Start content is awesome! It connects new users with the value of Sensu quickly and easily. I'd like to polish this content to make sure that users' first experience with Sensu inspires confidence.

  • Fix step numbers in "The Five Minute Install", either by condensing whitespace or using bold styling for step numbers.

fix list styling option 1fix list styling option 2

  • Look into bug with nav menu creating a visible index page under Quick Start.
  • Resolve duplicated content when no platform is selected in "Learn Sensu in 15 Minutes".
  • If possible, combine "Client Installation" and "The Five Minute Install".
  • Check for broken links using an automated, site-wide broken-link checker.
  • Complete steps 4 and 5 in "Learn Sensu in 15 Minutes".

4. Define feedback flows

Provide an explicit process for users to provide feedback on the docs. For long-form feedback, this could be a link to a GitHub issue template or a comment box within the docs site. For general positive feedback, I'd recommend a GitHub stars button.

GitHub stars button

5. Update metadata to promote sharing

I recommend prioritizing link unfurling as described in this issue. We want to reward users who share our docs with each other by providing neat, helpful unfurled messages.

Nice-to-Haves

  • More control over ordering in navigation menu: Hugo currently lists sections alphabetically, but it would be helpful for new users if we could move Quick Start and Guides to the top. (Frontmatter weight?)
  • Navigation link style: Use an icon or other style to create a visual link between the “Navigation” button and the navigation page.
  • Navigation menu awareness: Highlight first-level items in the sidebar menu to show where users are in the docs.
  • Search usability: Condense white space in search results, and enable keyboard-based navigation.
  • Dynamic table of contents: Automatic tables of contents that indicate where users are on the page.
  • Persist the individual page when switching versions: This functionality is covered by the "You're viewing documentation for an older or pre-release version" alert, but it would be great to provide this same functionality with the version switcher.

Discussion Topics

  • What's the history behind breaking out Extensions from Sensu Core?
  • Is it possible to provide a complete sample app?
  • Is there a defined process for code samples?
  • What's the PR review process?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment