From 1e0ea67e6f150f858e5a5a621ffdf183c48722d5 Mon Sep 17 00:00:00 2001 From: Desmi-Dizney <99777687+Desmi-Dizney@users.noreply.github.com> Date: Tue, 19 Apr 2022 21:59:59 -0500 Subject: [PATCH] Handbook editor pass - Brand (#5131) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All edits are recorded by line: 5 Replace: “positive,” with “positive” 7 Replace: “friendly” with “friendly,” 9 Replace: “confidence,” with “confidence”; Replace: “to always stay” with “always to stay” 11 Replace: “smart” with “wise” 15 Replace: “Mr” with “Mr.” 17 Delete space; Delete: “-”; Add: “,” 23 Replace: “becomes” with “Becomes” 25 Replace: “to work” with “work” 27 Replace: “Mr Rogering” with “Mr. Rogersing”; Replace: “writing” with “writing,”; Replace: “use” with “the use” 35 Replace: “".” with “."” 36 Replace: “".” with “."” 40 Replace: “case,” with “case” 41 Replace: “macOS” with “macOS.” 43 Replace: “are using” with “use”; Delete: “in the sentence” after “word”; Add: “in the sentence” after “capitalized”; Replace: “these words should also be” with “it should remain” 44 Replace: “Apple,” with “Apple”; Replace: “that we adhere to.” with “to which we adhere” 46 Add: “to” 47 Replace: “lowercase,” with “lowercase” 63 Replace: “Need” with “Do you need” 66 Replace: “Definitely” with “This is definitely”; Replace: “".” with “."” 70 Replace: “off” with “on”; Replace: “or” with “,”; Replace: “at” with “in” 71 Add: “it”before “in”; Delete: “you” after “write”; Replace: “that will” with “to” 80 capitalized and puntuated 81 capitalized and puntuated 82 capitalized and puntuated 83 capitalized and puntuated 84 capitalized and puntuated 85 capitalized and puntuated; Delete: “to take” after “to” 88 Replace: “bear in mind” with “remember”; Replace: “then please” with “please” 90 Replace: “level of quality” with “quality” 100 Replace: “looks,” with “looks” 104 Add: “them” 109 Replace: “as easy as possible” with “easy” 113 Replace: “this” with “this,” 115 Replace: “this” with “this,” 123 Add: “, if you opened it in preview” after “example”; Delete: “, if you opened it in preview., but But” after “32x32px,”; Add: “, but” after “32x32px,” 130 Replace: “Slack channels The following Slack channels are maintained by this group” with “These groups maintain the following slack channels” --- handbook/brand.md | 72 +++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/handbook/brand.md b/handbook/brand.md index b4d34c2d96..166244df67 100644 --- a/handbook/brand.md +++ b/handbook/brand.md @@ -2,29 +2,29 @@ ## Communicating as Fleet -- **Sound positive**, and assume positive intent. A positive tone helps to empower our users and encourages them to succeed with 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. +- **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 to always stay positive so as NOT to sound overconfident. +- **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 smart, but focusing on fear can lead to poor decisions. We NEVER use fear as a communication and marketing tactic. +- **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? +### What would Mr. Rogers say? -At Fleet, our voice and tone should be clear, simple, friendly, and inspiring - like [Mr. Rogers](https://en.wikipedia.org/wiki/Fred_Rogers) who had a deep understanding of these communication values. +At Fleet, our voice and tone should be clear, simple, friendly, and inspiring, like [Mr. Rogers](https://en.wikipedia.org/wiki/Fred_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... +Becomes... -- *Distributed workforces aren’t going anywhere anytime soon, **so it’s a great time** to **engage** with your **crew** and **help them** to work with your security team instead of around them.* +- *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 Rogering our writing we can emphasize positivity, optimism and encourage our readers to succeed. The example above also considers sentence flow and use of synonyms to reduce repetition. +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. @@ -114,19 +114,19 @@ Making edits to published social media posts gets a little tricky. Twitter, for ### 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”*. +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: -- **A**sk questions about your servers, containers, and laptops running **L**inux, **W**indows, and macOS +In **sentence case** we write titles as if they were sentences. For example: +- **A**sk questions about your servers, containers, and laptops running **L**inux, **W**indows, and macOS. -As we are using sentence case, only the first word of a heading and subheading is capitalized. However, if a word in the sentence would normally be capitalized (e.g. a [proper noun](https://www.grammarly.com/blog/proper-nouns/?&utm_source=google&utm_medium=cpc&utm_campaign=11862361094&utm_targetid=dsa-1233402314764&gclid=Cj0KCQjwg7KJBhDyARIsAHrAXaFwpnEyL9qrS4z1PEAgFwh3RXmQ24zmwmowAyOQbHngsI8W_F730aAaArrwEALw_wcB&gclsrc=aw.ds),) these words should also be 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, that we adhere to. +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](https://www.grammarly.com/blog/proper-nouns/?&utm_source=google&utm_medium=cpc&utm_campaign=11862361094&utm_targetid=dsa-1233402314764&gclid=Cj0KCQjwg7KJBhDyARIsAHrAXaFwpnEyL9qrS4z1PEAgFwh3RXmQ24zmwmowAyOQbHngsI8W_F730aAaArrwEALw_wcB&gclsrc=aw.ds),) 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 use osquery in sentences and headings -Osquery should always be written in lowercase, unless used to start a sentence or heading. For example: +### 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 **o**squery._ or @@ -142,15 +142,15 @@ See also [https://fleetdm.com/handbook/community#press-releases](https://fleetdm ## Email blasts -Need to send out a branded email blast to multiple recipients? +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. Definitely a "thing that doesn't scale".) +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 off one of our existing [email templates](https://www.figma.com/file/yLP0vJ8Ms4GbCoofLwptwS/?node-id=3609%3A12552) in Figma. If your Figma boots aren't comfortable (or you don't have edit access), your design could be a Google Drawing or Doc, or just a sketch on paper at a pinch. -- Bring your request to the digital experience team by posting in [their primary Slack channel](./people.md#slack-channels), 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](https://github.com/fleetdm/fleet/blob/de280a478834a7f85772bea4f552f953c65bb29e/website/views/emails/email-order-confirmation.ejs) for you, and write you a script that will 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.: +- First, design the email and content. The preferred method is to base the design on one of our existing [email templates](https://www.figma.com/file/yLP0vJ8Ms4GbCoofLwptwS/?node-id=3609%3A12552) 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](./people.md#slack-channels), 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](https://github.com/fleetdm/fleet/blob/de280a478834a7f85772bea4f552f953c65bb29e/website/views/emails/email-order-confirmation.ejs) 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"]'` @@ -159,17 +159,17 @@ Use "bcc" so recipients don't see each other's email addresses and send an email ### 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 +* 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, bear in mind 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](https://fleetdm.com/), then please do not merge. +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](https://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 level of quality seen on existing pages, ensure correct functionality, and check responsive behavior - starting widescreen and resizing down to ≈320px width. +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: @@ -179,22 +179,22 @@ If the action fails, please complete the following steps: ### Maintaining browser compatibility -A browser compatibility check of [fleetdm.com](https://fleetdm.com/) should be carried out monthly to verify that the website looks, and functions as expected across all [supported browsers](../docs/Using-Fleet/Supported-browsers.md). +A browser compatibility check of [fleetdm.com](https://fleetdm.com/) should be carried out monthly to verify that the website looks and functions as expected across all [supported browsers](../docs/Using-Fleet/Supported-browsers.md). - We use [BrowserStack](https://www.browserstack.com/users/sign_in) (logins can be found in [1Password](https://start.1password.com/open/i?a=N3F7LHAKQ5G3JPFPX234EC4ZDQ&v=3ycqkai6naxhqsylmsos6vairu&i=nwnxrrbpcwkuzaazh3rywzoh6e&h=fleetdevicemanagement.1password.com)) 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](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=bug%2C%3Areproduce&template=bug-report.md&title=), and assign for fixing. +- Document any issues in GitHub as a [bug report](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=bug%2C%3Areproduce&template=bug-report.md&title=), 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 it as easy as possible 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. +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. +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. +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 @@ -202,14 +202,14 @@ 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, the image would actually have dimensions of 32x32px, if you opened it in preview. 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. + * 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. ## Slack channels -The following [Slack channels are maintained](https://fleetdm.com/handbook/company#group-slack-channels) by this group: +These groups maintain the following [Slack channels](https://fleetdm.com/handbook/company#group-slack-channels): | Slack channel | [DRI](https://fleetdm.com/handbook/company#group-slack-channels) | |:----------------------------|:--------------------------------------------------------------------|