Knowledge Base Style Guide

Summarize your article content to let people quickly see if their answer is here, and to help search engines find it too.

Every article should have a "Note" callout at the top to explain what plans (Team, Business, Enterprise) it applies to and also what roles (Org Admin, Org Manager, Org Member, Org Visitor).

This article applies to:

All plans

All roles

Table of Contents

  1. Retrium Voice
  2. Formatting
  3. Article Settings
  4. Callouts
  5. GIFs
  6. Screenshots
  7. Videos
  8. FAQs

We use a Table of Contents (ToC) section at the top of any article that has two more distinct sections where each section is also longer than one paragraph.


Retrium Voice

Adapted from our Voice Position in the Retrium Brand Guidelines, our overall voice should be:

Trait What That Means To Us
Positive We strive to uplift and encourage teams.
Approachable From the experienced agilist to the new startup, we provide tools and guidelines that benefit everyone.
Purposeful We always strive to provide information and guidance that benefits customers and prospects as effectively as possibly.

Other things to consider:

  • Avoid metaphors, similes, and idioms
  • Avoid filler words ("simply", "just", etc.) and wordiness as much as possible
  • Experienced with Agile (uses industry terminology), but still accessible for those new to Agile

↑ Back to top (links to "table-of-contents" anchor at top of page)


Formatting

Referencing Retrium Navigation (Buttons, Links, Tabs, etc.)

When referencing buttons, links, and tabs within Retrium, bold the referenced item and match the case used in-app. For example:

Navigate to the Administration tab, then click...

Italics

Italics are only to be used in rare cases, such as referencing a book or blog title. For example:

In their book Agile Retrospectives: Making Good Teams Great, Derby and Larsen emphasize the need for...

Lists

Bulleted list

  • Use when listing features
  • Specific examples

Numbered list

  1. Anything introduced as a number (i.e. There are three ways to do xyz)
  2. Step-by-step directions on how to do something within Retrium


↑ Back to top


Article Settings

Be sure to add the article to the appropriate category (and subcategory, if applicable).

We also need to add tags to ensure people searching can easily find what they're looking for, especially if an article addresses more than one topic. For example, the What actions can I take after a retrospective has ended? article addresses the retrospective history, exporting retrospective data, and deleting a retrospective. These are the current tags (as of the time of writing) for that article:

↑ Back to top


Callouts

💡This type of callout is a "Tip". Tips should be used for helpful hints or best practices. Tips can also be used for calling out related actions you can take in the app, but aren't necessarily part of the steps of the article. Add a lightbulb emoji at the beginning of any tip.

The "Note" callout type is used at the top of an article to explain what audience the article pertains to. Notes should not be used elsewhere in articles.

❗️This type of callout is a "Caution". Cautions should be used as an important heads up or FYI that something may happen as a result that the user might not be aware of. Use a red exclamation mark emoji at the beginning of any caution.

⚠️ This type of callout is a "Warning". Warnings should be used when an action might cause serious harm to a users account or result in a deleted account; add a warning sign emoji at beginning of any warning.

 

↑ Back to top


GIFs

Be sure to include alt text via HubSpot for SEO and accessibility best practices.

Example:

GIF demonstrating how to change the organization name. First, go to the Administration tab. Then, click to change the name under the General Settings section. Finally, click Save.

GIFs should be uploaded to HubSpot image library under 2022 Knowledge Base Refresh (selecting the most appropriate folder within.) You can browse for files or drag and drop. Once uploaded to HubSpot, you can click the image to insert it:

Screen Recording 2022-06-09 at 02-57-09 PM-gif

↑ Back to top


Screenshots

Use the Spotlight Rectangle Tool in CloudApp to annotate important information in a screenshot. You can also redact sensitive info in a screenshot if needed. Be sure to include alt text via HubSpot for SEO and accessibility best practices.

Example:

Screenshot of Members tab. The More menu (three dots) is open next to an Org Admin, with the "Remove user" option highlighted.

Once annotated, screenshots should be uploaded to HubSpot image library under 2022 Knowledge Base Refresh (selecting the most appropriate folder within.) You can browse for files or drag and drop. Once uploaded to HubSpot, you can click the image to insert it:

↑ Back to top


Videos

Videos are uploaded to Wistia and embedded in HubSpot articles using the Insert > Embed menu. We use Wistia's recommended responsive embed code and set the padding=60%.

The below video is just an example, but contains all the pieces (except voiceover) that our Knowledge Base videos should have:

  1. Retrium video "swoosh" logo bumper at beginning and end
  2. "How To" bumper
  3. Screen recording that follows the action as needed
  4. Chapters added (not necessary for a video this short, but added to show functionality)
  5. Voiceover (include transcript for SEO and accessibility best practices)

Once you have the video uploaded in Wistia and the embed code copied, here's how to embed it in the HubSpot article:

↑ Back to top


(WIP) FAQs

This section is a work in progress. We don't yet use the accordion format for FAQs, but it's something that's being explored.

https://supfort.com/pure-css-accordion-without-javascript

Retrium can support as many as 250 participants. However, even a meeting with 20 people can be challenging to manage. Learn more about running large retrospectives!

Your content goes here.

Your content goes here.