fleet/handbook/brand.md

Brand

Communicating as Fleet

• Sound positive and assume positive intent. A positive tone helps to empower our users and encourages them to succeed with Fleet.

• Be relatable, friendly, and sincere. Being relatable reminds our users that they're talking to another human that cares. Use simple words and sentences, especially in technical conversations.

• Project confidence and be informative. Clearly tell users what they need to know, remembering always to stay positive so as NOT to sound overconfident.

• Manage risk, not fear. Educate users about security threats positively. Risk management is wise, but focusing on fear can lead to poor decisions. We NEVER use fear as a communication and marketing tactic.

• Consider the meaning of words. We never want to offend people or sound judgemental. Industry jargon that was once commonly used may now be considered offensive and should be avoided.

What would Mr. Rogers say?

At Fleet, our voice and tone should be clear, simple, friendly, and inspiring, like Mr. Rogers who had a deep understanding of these communication values.

Consider the example tweets below. What would Mr. Rogers say?

• Distributed workforces aren’t going anywhere anytime soon. It’s past time to start engaging meaningfully with your workforce and getting them to work with your security team instead of around them.

Becomes...

• Distributed workforces aren’t going anywhere anytime soon, so it’s a great time to engage with your crew and help them work with your security team instead of around them.

By Mr. Rogersing our writing, we can emphasize positivity, optimism and encourage our readers to succeed. The example above also considers sentence flow and the use of synonyms to reduce repetition.

Another example to consider is industry jargon that may now be inappropriate. While the term "responsible vulnerability disclosure" has been used for decades, it supposes that people who use a different process are irresponsible. Using coordinated disclosure is a more positive way to discuss the issue.

Writing at Fleet

Writing at Fleet shares the same principles as Communicating as Fleet. Every piece of content we write should be consistent with our company and brand values. To help succeed, we encourage our writers to apply a design thinking approach to their writing by following these principles:

• Empathize - Who is the reader? Why will they read it? What do they hope to get from it?
• Define - What is the subject? What action do you want from the reader?
• Ideate and collaborate - Create an outline of what you plan to write. Interview team members or friends of Fleet to help you.
• Prototype - Write a draft and see how it goes. Draft quickly, iterate, and don't be scared to throw it out if it's not working.
• Test - Revise, edit, proofread, repeat. Revise, edit, proofread, repeat. Revise, edit... Ok, you get the idea 😵‍💫

Editing written content

Jokes above aside, testing is an integral part of the design thinking approach to writing. It ties in with the spirit of our company value, Ownership. Part of that value is to move quickly and help unblock our team members and contributors to deliver value. When writing at Fleet, our writers need to take ownership of editing and self-check their work before publishing or submitting pull requests. Having an obsession with details is helpful. So is Grammarly, to which all writers and editors (yes, we do have editors, more on them later) have access. Let's take a look at that now.

Grammarly

All of our writers and editors have access to Grammarly, which comes with a handy set of tools, including:

• Style guide, which helps us write consistently in the style of Fleet.
• Brand tones to keep the tone of our messaging consistent with just the right amount of confidence, optimism, and joy.
• Snippets to turn commonly used phrases, sentences, and paragraphs (such as calls to action, thank you messages, etc.) into consistent, reusable snippets to save time.

Our favorite Grammarly feature is the tone detector. It's excellent for keeping messaging on-brand and helps alleviate the doubt that often comes along for the ride during a writing assignment. Take a look at their video that sums it up better than this.

For editors

While we encourage and equip our writers to succeed by themselves in editing quests, tpyos are inevitable. Here's where the Fleet editor steps in.

The following is our handy guide to editor bliss at Fleet, but first, let's start by listing common content types that require an editor pass.

• Docs and Handbook pages.
• Articles, release posts, and press releases.
• Social media posts.

How to edit recently merged Pull Requests for the handbook and docs

We approach editing retrospectively for pull requests (PRs) to handbook and docs pages. Remember our goal above about moving quickly and reducing time to value for our contributors? By editing for typos and grammatical errors after-the-fact, we avoid the editor becoming a bottleneck who blocks PRs from being merged quickly. Here's how to do it:

Note: Contributors are not required to request reviews from editors for handbook and docs changes.

1. Check that the previous day's edits are formatted correctly on the website (more on this in the note below.)
2. Use GitHub's history feed to see a list of all changes made over time to the handbook and docs. You can access the history feeds from the following links:

• Handbook history
• Docs history

3. From the list of recently merged PRs, look at the files changed for each and then:

• Scan for typos and grammatical errors.
• Check that the tone aligns with our Communicating as Fleet guidelines and that Grammarly's tone detector is on-brand.
• Check that Markdown is formatted correctly.
• Remember, Do not make edits to this page. It's already merged.

4. Instead, navigate to the page in question on the website and submit a new PR to make edits - making sure to request a review from the maintainer of that page.
5. Comment on the original PR to keep track of your progress. Comments made will show up on the history feed. E.g., "Edited, PR incoming" or "LGTM, no edits required."
6. Watch this short video to see this process in action.

Note: The Fleet website may render Markdown differently from GitHub's rich text preview. It's essential to check that PRs merged by the editor are displaying as expected on the site. It can take a few minutes for merged PRs to appear on the live site, and therefore easy to move on and forget. It's good to start the ritual by looking at the site to check that the previous day's edits are displaying as they should.

How to edit articles, release posts, and press releases

This type of content comes in two flavors: draft articles and published articles.

For draft articles, please refer to Publishing articles on fleetdm.com.

For making edits to published articles:

1. Log in to Medium.
2. Find the article to edit and select "Edit story" from the hotdog menu (•••).
3. Scan for typos and grammatical errors.
4. Check that the tone aligns with our Communicating as Fleet guidelines and that Grammarly's tone detector is on-brand.
5. Remember, this article is already published, so if you're unsure about any edits, it doesn't hurt to check in with the original author.
6. Hit "Save and publish," and you're all done.

How to edit social media posts

In the world of the Fleet editor, there are two types of social media posts; those scheduled to be published and those published already.

Refer to Posting on social media as Fleet for details on editing draft social media posts.

Making edits to published social media posts gets a little tricky. Twitter, for example, doesn't allow editing of tweets, so the only way to make an edit is to remove the tweet and post it again.

1. Post the tweet in the #g-growth Slack channel and tag the Digital Experience lead.
2. Decide whether to remove the tweet. There's a tradeoff between us striving for perfection vs. losing the engagements that the tweet may have already generated.
3. Suggest edits in the Slack thread for the Growth team to include and re-post.

Voice and tone guidelines

How to use our name

When talking about Fleet the company, we stylize our name as either "Fleet" or "Fleet Device Management." For Fleet the product, we say either “Fleet” or “Fleet for osquery.”

How to write headings & subheadings

Fleet uses sentence case capitalization for all headings across Fleet EE, fleetdm.com, our documentation, and our social media channels. In sentence case we write titles as if they were sentences. For example:

• Ask questions about your servers, containers, and laptops running Linux, Windows, and macOS.

As we use sentence case, only the first word of a heading and subheading is capitalized. However, if a word would normally be capitalized in the sentence (e.g. a proper noun,) it should remain capitalized in the heading.

Note the capitalization of “macOS” in the example above. Although this is a proper noun, macOS uses its own style guide from Apple to which we adhere.

How to use osquery in sentences and headings

Osquery should always be written in lowercase unless used to start a sentence or heading. For example:

• Open source software, built on osquery.

or

• Osquery and Fleet provide structured, convenient access to information about your devices.

Brand resources

To download official Fleet logos, product screenshots, and wallpapers, head over to our brand resources page.

See also https://fleetdm.com/handbook/community#press-releases for our press-release boilerplate.

Email blasts

Do you need to send out a branded email blast to multiple recipients?

The manual way

Use "bcc" so recipients don't see each other's email addresses and send an email manually using Gmail. (Good for small lists. This is definitely a "thing that doesn't scale.")

The automated way

• First, design the email and content. The preferred method is to base the design on one of our existing email templates in Figma. If your Figma boots aren't comfortable (or you don't have edit access), your design could be a Google Drawing, Doc, or just a sketch on paper in a pinch.

• Bring your request to the digital experience team by posting in their primary Slack channel, along with your urgency/timeline. The digital experience team will finalize the design and language for consistency, then fork and customize one of the existing email templates for you, and write a script to deliver it to your desired recipients. Then, digital experience will merge that, test it by hand to make sure it's attractive and links work, and then tell you how to run the script with e.g.:

  sails run deliver-release-announcement --emailAddresses='["foo@example.com","bar@example.com"]'

Fleet website

Responding to a 5xx error on fleetdm.com

Production systems can fail for various reasons, and it can be frustrating to users when they do, and customer experience is significant to Fleet. In the event of system failure, Fleet will:

• investigate the problem to determine the root cause.
• identify affected users.
• escalate if necessary.
• understand and remediate the problem.
• notify impacted users of any steps they need to take (if any). If a customer paid with a credit card and had a bad experience, default to refunding their money.
• Conduct an incident post-mortem to determine any additional steps we need (including monitoring) to take to prevent this class of problems from happening in the future.

When can I merge a change to the website?

When merging a PR to master, remember that whatever you merge to master gets deployed live immediately. So if the PR's changes contain anything that you don't think is appropriate to be seen publicly by all guests of fleetdm.com, please do not merge.

Merge a PR (aka deploy the website) when you think it is appropriately clean to represent our brand. When in doubt, use the standards and quality seen on existing pages, ensure correct functionality, and check responsive behavior - starting widescreen and resizing down to ≈320px width.

The "Deploy Fleet Website" GitHub action failed

If the action fails, please complete the following steps:

1. Head to the fleetdm-website app in the Heroku dashboard and select the "Activity" tab.
2. Select "Roll back to here" on the second to most recent deploy.
3. Head to the fleetdm/fleet GitHub repository and re-run the Deploy Fleet Website action.

Maintaining browser compatibility

A browser compatibility check of fleetdm.com should be carried out monthly to verify that the website looks and functions as expected across all supported browsers.

• We use BrowserStack (logins can be found in 1Password) for our cross-browser checks.
• Check for issues against the latest version of Google Chrome (macOS). We use this as our baseline for quality assurance.
• Document any issues in GitHub as a bug report, and assign them for fixing.
• If in doubt about anything regarding design or layout, please reach out to the Design team.

How to make usability changes to the website

We want to make easy to learn how to manage devices with Fleet. Anyone inside or outside the company can suggest changes to the website to improve ease of use and clarity.

To propose changes:

1. Decide what you want to change. A small change is the best place to start.
2. Wireframe the design. Usually, digital experience does this, but anyone can contribute.
3. Present your change to the website DRI. They will approve it or suggest revisions.
4. Code the website change. Again, digital experience often does this, but anyone can help.
5. Measure if the change made it easier to use. This can be tricky, but the growth team will have ideas on how to do this.

How to export images for the website

In Figma:

1. Select the layers you want to export.
2. Confirm export settings and naming convention:

• item name - color variant - (css)size - @2x.fileformat (e.g., os-macos-black-16x16@2x.png)
• note that the dimensions in the filename are in CSS pixels. In this example, if you opened it in preview the image would actually have dimensions of 32x32px, but in the filename, and in HTML/CSS, we'll size it as if it were 16x16. This is so that we support retina displays by default.
• File extension might be .jpg or .png.
• Avoid using SVGs or icon fonts.

3. Click the Export button.

Rituals

The following table lists the Brand group's rituals, frequency, and Directly Responsible Individual (DRI).

Ritual	Frequency	Description	DRI
Documentation quality	Daily	Review pull requests to the docs for spelling, punctuation and grammar.	Desmi Dizney
Handbook quality	Daily	Review pull requests to the handbook for spelling, punctuation and grammar.	Desmi Dizney
Tweet review	Daily	Review tweets for tone and brand consistency.	Mike Thomas
Weekly article review	Weekly	Review articles for tone and brand consistency.	Mike Thomas
Weekly article graphic	Weekly	Create a graphic for the weekly article	Mike Thomas
Digital experience planning	Three weeks	Prioritize and assigns issues to relevant personnel based on current goals and quarterly OKRs	Mike Thomas
OKR review	Three weeks	Review the status of current OKRs.	Mike Thomas
OKR planning	Quarterly	Plan next quarter's OKRs	Mike Thomas
Browser compatibility check	Monthly	Check browser compatibility for the website	Eric Shaw

Slack channels

These groups maintain the following Slack channels:

Slack channel	DRI
#g-digital-experience	Mike Thomas
#oooh-websites	Mike Thomas
#oooh-automation	Mike McNeil
#g-people	Eric Shaw
#help-onboarding	Eric Shaw
#help-finance	Eric Shaw
#help-brex-memos	Nathan Holliday