diff --git a/handbook/company/communications.md b/handbook/company/communications.md index 5f63d8312..6b277f4d1 100644 --- a/handbook/company/communications.md +++ b/handbook/company/communications.md @@ -3,6 +3,917 @@ Fleet's [open-core](https://www.heavybit.com/library/video/commercial-open-source-business-strategies) style of communication and the [tools we use](https://docs.google.com/spreadsheets/d/170qjzvyGjmbFhwS4Mucotxnw_JvyAjYv4qpwBrS6Gl8/edit?usp=sharing) are part of the company's DNA and essential to moving Fleet into the future. +## Meetings + +- **Plan to join meetings on time.** At Fleet, we start on time and do not wait for folks to join. As most of our meetings are conducted over zoom, please join with a working microphone and with your camera on whenever possible. Being even a few minutes late can make a big difference and slow your meeting counterparts down. When in doubt, show up a couple of minutes early. +- **Turning on your camera** allows for more complete and intuitive verbal and non-verbal communication. Feel free to leave your camera on or turn it off when joining meetings with new participants you might not be familiar with yet. Turn your camera on when you lead or cohost a meeting, or when you present your work during a demo session. +- **If you would prefer not to be on YouTube** when presenting on a meeting, you can prep your demo ahead of the meeting and communicate to your manager who will present for you. It's always ok to do this. +- **Be warm.** It's okay to spend the first minute or two of a meeting being present and making small talk. Since we are all remote, it's easy to miss out on hallway chatter and human connections that happen in [meatspace](https://www.dictionary.com/browse/meatspace). Use this time together during the first minute to say "Hi!" Then you can jump into the topics to be discussed. + + + +### Internal meeting scheduling + +Fleet uses the Zoom add-on for Google Calendar to schedule meetings (exceptions are customers that are non-negotiably required to use a different tool) when we [create calendar events](https://support.google.com/calendar/answer/72143?hl=en&ref_topic=10510646&sjid=7187599067132459840-NA#zippy=%2Cclick-an-empty-time-in-your-calendar). +Our Zoom meetings are configured to let participants join before the host arrives, to make sure meetings start on time even if the host isn't there. + +To schedule a meeting within Fleet: +- To add a Zoom meeting to a calendar event, click the "Add video conferencing" dropdown and select "Zoom Meeting." Google Calendar will automatically add the Zoom meeting details and instructions to join the event. +- Enter the `@fleetdm.com` emails for each participant into the "Add guests" box in Google Calendar, and the calendar availability for each participant will appear in your view. +- Select a meeting time, the participants will automatically be invited and a video conference will be attached to the invite (this can save a lot of communication overhead when scheduling with multiple participants). + +It is important to [set your workinghours](https://support.google.com/calendar/answer/7638168?hl=en&co=GENIE.Platform%3DDesktop) in Google Calendar and block out any personal time/events/PTO, so that team members do not inadvertently schedule a time when you are not available. +- Many team members use the free tier of [reclaim.ai](https://reclaim.ai/) to synchronize personal event times (without event details) into their work calendars. +It is also common practice to block out time for focused work. + +
In an all-remote company, "face time" matters. Remember: even if someone's calendar is open, they have other work to do. Limiting (or batching up) internal meetings can enable longer, uninterrupted stretches of deep work.
+ + +### Modifying an event organized by someone else + +To edit an event where someone else at Fleet is the organizer, you can first subscribe to their calendar in Google Calendar and then edit the event on their calendar. Your edits will automatically apply to all attendees. +This works because every Fleetie grants edit access to everyone else at Fleet as part of onboarding. + +### External meeting scheduling + +When scheduling external meetings, provide external participants with a +[Calendly](https://calendly.com) link to schedule with the relevant internal participants. If you +need a Calendly account, reach out to `mikermcneil` via Slack. + + +## Zoom + +We use [Zoom](https://zoom.us) for virtual meetings at Fleet, and it is important that every team member feels comfortable hosting, joining, and scheduling Zoom meetings. +By default, Zoom settings are the same for all Fleet team members, but you can change your personal settings on your [profile settings](https://zoom.us/profile/setting) page. +Settings that have a lock icon next to them have been locked by an administrator and cannot be changed. Zoom administrators can change settings for all team members on the [account settings page](https://zoom.us/account/setting) or for individual accounts on the [user management page](https://zoom.us/account/user#/). + + +## Slack + +At Fleet, we do not send internal emails to each other. Instead, we prefer to use [Slack](https://www.linkedin.com/pulse/remote-work-how-set-boundaries-when-office-your-house-lora-vaughn/) to communicate with other folks who work at Fleet. +We use threads in Slack as much as possible. Threads help limit noise for other people following the channel and reduce notification overload. +We configure our [working hours in Slack](https://slack.com/help/articles/360025054173-Set-up-Slack-for-work-hours-) to make sure everyone knows when they can get in touch with others. + +### Slack channel prefixes +We have specific channels for various topics, but we also have more general channels for the teams at Fleet. +We use these prefixes to organize the Fleet Slack: + * ***g-***: for team/group channels *(Note: "g-" is short for "grupo" or "group")*. + * ***oooh-***: used to discuss and share interesting information about a topic. + * ***help-***: for asking for help on specific topics. + * ***at*** or ***fleet-at***: for customer channels. + * ***2023-***: for temporary channels _(Note: specify the relevant year in four digits, like "YYYY-`)_ + +#### Slack communications and best practices +In consideration of our team, Fleet avoids using global tags in channels (i.e. @here, @channel, etc). + 1. What about polls? Good question, Fleeties are asked to post their poll in the channel and @mention the teammates they would like to hear from. + 2. Why does this matter? Great question! The Fleet [culture](https://fleetdm.com/handbook/company#culture) is pretty simple: think of others, and remember the company [Values](https://fleetdm.com/handbook/company#values). + + +## Levels of confidentiality + +Fleet uses these levels to standardize a commitment to minimal esotericism across the company. +- **Public:** _Share with anyone, anywhere in the world_ +- **Confidential:** _Share only with team members who've signed an NDA, consulting agreement, or employment agreement_ +- **Classified:** _Share only with founders of Fleet, business operations, and/or the people involved. e.g., US social security numbers during hiring_ + + +### Legend for Google doc titles + +Fleet uses these levels to standardize a commitment to minimal esotericism across the company. +- **"Public":** _(Available to public)_ +- _(Confidential - for Fleet eyes only)_ +- **"¶":** _(E-group - Direct reports the the CEO)_ +- **"¶¶":** _(Classified - Founders and BizOps)_ +- **"¶¶¶":** _(Founders and board members)_ + + +## Email relays + +There are several special email addresses that automatically relay messages to the appropriate people at Fleet. Each email address meets a minimum response time ("Min RT"), expressed in business hours/days, and has a dedicated, directly responsible individual (DRI) who is responsible for reading and replying to emails sent to that address. You can see a list of those email addresses in ["Contacting Fleet" (private Google doc)](https://docs.google.com/document/d/1tE-NpNfw1icmU2MjYuBRib0VWBPVAdmq4NiCrpuI0F0/edit#). + + +## Github + +### Making a pull request + +Our handbook and docs pages are written in Markdown and are editable from our website (via GitHub). Follow the instructions below to propose an edit to the handbook or docs. +1. Click the _"Edit page"_ button from the relevant handbook or docs page on [fleetdm.com](https://www.fleetdm.com) (this will take you to the GitHub browser). +2. Make your suggested edits in the GitHub. +3. Click _"Commit changes...."_ +4. Give your proposed change a title or _["Commit message"](https://about.gitlab.com/topics/version-control/version-control-best-practices/#write-descriptive-commit-messages)_ and optional _"Extended description"_ (good commit messages help page maintainers quickly understand the proposed changes). + - **Note:** _Keep commit messages short and clear. (e.g. "Add DRI automation")_ +4. Click _"Propose changes"_ +5. Request a review from the page maintainer, and finally, press “Create pull request.” +6. GitHub will run a series of automated checks and notify the reviewer. At this point, you are done and can safely close the browser page at any time. +8. Check the “Files changed” section on the Open a pull request page to double-check your proposed changes. + +### Merging changes +When merging a PR to the master branch of the [Fleet repo](https://github.com/fleetdm/fleet), remember that whatever you merge gets deployed live immediately. Ensure that the appropriate quality checks have been completed before merging. [Learn about the website QA process](#quality). + +When merging changes to the [docs](https://fleetdm.com/docs), [handbook](https://fleetdm.com/handbook), and articles, make sure that the PR’s changes do not contain inappropriate content (goes without saying) or confidential information, and that the content represents our [brand](#brand) accordingly. When in doubt reach out to the product manager of the [website group](https://fleetdm.com/handbook/company/product-groups#website-group) in the [#g-website](https://fleetdm.slack.com/archives/C058S8PFSK0) channel on Slack. + +### Editing a merged pull requests + +We approach editing retrospectively for pull requests (PRs) to handbook pages. Remember our goal above about moving quickly and reducing time to value for our contributors? We avoid the editor becoming a bottleneck for merging quickly by editing for typos and grammatical errors after-the-fact. Here's how to do it: + +1. Check that the previous day's edits are formatted correctly on the website (more on this in the note below.) +2. Use the [Handbook history](https://github.com/fleetdm/fleet/commits/main/handbook) feed in GitHub to see a list of changes made to the handbook. +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](https://fleetdm.com/handbook/brand#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](https://www.loom.com/share/95d4525a7aae482b9f9a9470d446ce9c) 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. + + +##### Linking to a location on GitHub + +When adding a link to any text in the docs, handbook, or website always be sure to use the canonical form of the URL (e.g. _"https//www.fleetdm.com/handbook/..."_). + +Navigate to the file's location on GitHub, and press "y" to transform the URL into its canonical form. + +#### Fixing a broken link + +For instance when a broken link is discovered on fleetdm.com, always check if the link is a relative link to a location outside of `/docs`. + +An example of a link that lives outside of `/docs` is: + +``` +../../tools/app/prometheus +``` + +If the link lives outside `/docs`, head to the file's location (in this case, [https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)](https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)), and copy the full URL into its canonical form (a version of the link that will always point to the same location) ([https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml](https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml)). Replace the relative link with full URL. + + +#### Meta tags + +##### Page order + +The order we display documentation pages on fleetdm.com is determined by `pageOrderInSection` meta tags. These pages are sorted in their respective sections in **ascending** order by the `pageOrderInSection` value. Every Markdown file (except readme and faq pages) in the `docs/` folder must have a meta tag with a positive 'pageOrderInSection' value. + +We leave large gaps between values to make future changes easier. For example, the first page in the "Using Fleet" section of the docs has a `pageOrderInSection` value of 100, and the next page has a value of 200. The significant difference between values allows us to add, remove and reorder pages without changing the value of multiple pages at a time. + +When adding or reordering a page, try to leave as much room between values as possible. If you were adding a new page that would go between the two pages from the example above, you would add `` to the page. + +##### Page description + +TODO: Document. + +#### Images + +Try to keep images in the docs at a minimum. Images can be a quick way to help users understand a concept or direct them towards a specific user interface(UI) element. Still, too many can make the documentation feel cluttered and more difficult to maintain. + +When adding images to the Fleet repo, follow these guidelines: + +- UI screenshots should be a 4:3 aspect ratio (1280x960). This is an optimal size for the container width of the docs and ensures that content in screenshots is as clear as possible to view in the docs (and especially on mobile devices). +- You can set up a custom preset in the Google Chrome device toolbar (in Developer Tools) to quickly adjust your browser to the correct size for taking a screenshot. +- Keep the images as simple as possible to maintain. Screenshots can get out of date quickly as UIs change. +- Exclude unnecessary images. Images should be used to help emphasize information in the docs, not replace it. +- Minimize images per doc page. For doc maintainers and users, more than one or two per page can get overwhelming. +- The goal is for the docs to look good on every form factor, from 320px window width all the way up to infinity. Full window screenshots and images with too much padding on the sides will be less than the width of the user's screen. When adding a large image, make sure it is easily readable at all widths. + +Images can be added to the docs using the Markdown image link format, e.g., `![Schedule Query Sidebar](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/add-new-host-modal.png)` +The images used in the docs live in `docs/images/`. Note that you must provide the URL of the image in the Fleet GitHub repo for it to display properly on both GitHub and the Fleet website. + +> Note that the instructions above also apply to adding images in the Fleet handbook. + + + +### GitHub labels +We use special characters to define different types of GitHub labels. By combining labels, we +organize and categorize GitHub issues. This reduces the total number of labels required while +maintaining an expressive labeling system. For example, instead of a label called +`platform-dev-backend`, we use `#platform :dev ~backend`. + +| Special character | Label type | Examples | +|:------------------|:------------|:------------------------------------| +| `#` | Noun | `#platform`, `#interface`, `#agent` +| `:` | Verb | `:dev`, `:research`, `:design` +| `~` | Adjective | `~blocked`, `~frontend`, `~backend` + +## Writing + +Learn how to communicate as Fleet with guidelines for tone of voice, our approach, grammar and mechanics, and more. + +### Writing style + - Infuse the core [values](https://fleetdm.com/handbook/company#values) into everything you write. + - Read and reread, then rewrite to make it shorter. Use links rather than explanations, short sentences. + - Get to where you feel like it’s really good, short, simple, and clear, hack away at any word that’s too confusing. + - Don’t sound formal, sound welcoming so that anyone can understand. Translate "[puffery](https://www.linkedin.com/pulse/puffery-adam-frankl%3FtrackingId=SBVWxzqXTBm9qlO7Rw3ddw%253D%253D/?trackingId=SBVWxzqXTBm9qlO7Rw3ddw%3D%3D)" into "ease of use" or "readability". + - Apply the advice about writing linked from the company values (the [Paul Graham](http://www.paulgraham.com/simply.html) essays). + - Create headings that make good permalinks, use links and add missing links. Indicate links by highlighting words that describe the content (Better SEO than lighting up “click here”). + - Don’t duplicate content, link to other places like the [values](https://fleetdm.com/handbook/company#values) or [“why this way”](https://fleetdm.com/handbook/company/why-this-way#why-this-way), but don’t make it awkward. + - A big goal is to be able to link directly to this stuff when something comes up as a gentle way to remind and train using the foundation we've already built. + - Avoid unnecessary changes, and don’t change headings lightly (it breaks handbook links people might have put in an external article or have in their email inbox somewhere). + - Read your PRs, check it carefully with each change and edit until the diff looks good. + - Check preview mode in GitHub to make sure the format renders correctly. If you look at your diff and notice unintentional changes, remove them. + + +### What would Mister Rogers say? +[*Mister Rogers’ Neighborhood*](https://en.wikipedia.org/wiki/Mister_Rogers%27_Neighborhood) was one of the longest-running children’s TV series. That’s thanks to [Fred Rogers](https://en.wikipedia.org/wiki/Fred_Rogers)’ communication skills. He knew kids heard things differently than adults. So, he checked every line to avoid confusion and encourage positivity. + +Our audience is a little older. But just like the show, Mister Rogers’ method is appropriate for all ages. Here are some steps you can take to communicate like Mister Rogers: + +- State the idea you want to express as clearly as possible. +- Rephrase the idea in a positive manner. +- Rephrase the idea, directing your reader to authorities they trust. +- Rephrase the idea to eliminate anything that may not apply to your reader. +- Add a motivational idea that gives your reader a reason to follow your advice. +- Rephrase the new statement, repeating the first step. + +Consider this example tweet. + +
- 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.
+ +What would Mister Rogers say? The tweet could look something like this... + +
- Distributed workforces are here to stay. So, it’s a great time to help employees work with your security experts (and not around them). Because stronger teams get to celebrate more victories.
+ +By Mister Rogersing our writing, we can encourage our readers to succeed by emphasizing optimism. You might not be able to apply all of these steps every time. That’s fine. Think of these as guidelines to help you simplify complex topics. + + +### 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. + + +### Using sentence case and capitalization + +#### Sentence case +Fleet uses sentence case capitalization for all headings, subheadings, button text in the Fleet product, fleetdm.com, the documentation, the handbook, marketing material, direct emails, in Slack, and in every other conceivable situation. + +In sentence case, we write and capitalize words as if they were in sentences: + +
Ask questions about your servers, containers, and laptops running Linux, Windows, and macOS.
+ +As we use sentence case, only the first word is capitalized. But, if a word would normally be capitalized in the sentence (e.g., a proper noun, an acronym, or a stylization) it should remain capitalized. + +- Proper nouns _("Nudge", "Skimbleshanks", "Kleenex")_ + - "Yeah, we use Nudge" + - "Introducing our friend Skimbleshanks" + - "Please, can I have a Kleenex?" +- Acronyms _("MDM", "REST", "API", "JSON")_ + - "MDM commands in Fleet are available over a REST API that returns JSON" +- Stylizations _("macOS", "osquery", "MySQL") + - "Although 'macOS' is a proper noun, macOS uses its own style guide from Apple, to which we adhere" + - "Zach is the co-creator of osquery" + - "Does it work with MySQL?" + +- ***Struggling with this?*** It takes some adjustment, and you need repetitions of seeing things written this way and correcting yourself. Contributors have given feedback that this [opinionated solution](https://fleetdm.com/handbook/company/why-this-way#why-does-fleet-use-sentence-case) is a huge relief once you build the habit of sentence case capitalization. You don't have to think as hard, nor choose between flouting and diligently adhering to the style guide. + +#### Capitalization and proper nouns +- **Fleet:** When talking about Fleet the company, we stylize our name as either "Fleet" or "Fleet Device Management." +- **Fleet the product:** We say either “Fleet” or “Fleet for osquery.” +- **Core team members:** Team members who've signed an NDA employment agreement, are “Fleeties.” +- **Group of devices or virtual servers:** Use "fleet" or "fleets" (lowercase). +- **Osquery:** Osquery should always be written in lowercase unless used to start a sentence or heading. + + +#### Device vs endpoint +- When talking about a users' computer, we prefer to use "device" over _endpoint._ Devices in this context can be a physical device or virtual instance that connect to and exchange information with a computer network. Examples of devices include mobile devices, desktop computers, laptop computers, virtual machines, and servers. + + +### Headings +Headings help readers quickly scan content to find what they need and guide readers through your writing. Organize page content using clear headings specific to the topic they describe. + +While our readers are more tech-savvy than most, we can’t expect them to recognize queries by SQL alone. Avoid using code for headings. Instead, say what the code does and include code examples in the body of your document. + +Keep headings brief, organized, and in a logical order: +- H1: Page title +- H2: Main headings +- H3: Subheadings +- H4: Sub-subheadings + +Try to stay within three or four heading levels. Detailed documents may use more, but pages with a simpler structure are easier to read. + +#### Punctuation in headings +Fleet headings do not use end punctuation unless the heading is a question: + +
Learn how to use osquery, nanoMDM, and Nudge to manage and monitor laptops and servers running Linux, Windows, ChromeOS, and macOS
+ +If the heading is a question, end the heading with a question mark. + +### Grammar mechanics + +#### Contractions +They’re great! Don’t be afraid to use them. They’ll help your writing sound more approachable + +#### Ampersands +(&) Only use ampersands if they appear in a brand name, or if you’re quoting the title of an article from another source. Otherwise, write out “and”. + +#### Commas +When listing three or more things, use commas to separate the words. This is called a serial comma. + +✅ **Do:** Fleet is for IT professionals, client platform engineers, and security practitioners. + +❌ **Don’t:** Fleet is for IT professionals, client platform engineers and security practitioners. + +Aside from the serial comma, use commas, as usual, to break up your sentences. If you’re unsure whether you need a comma, saying the sentence aloud can give you a clue. If you pause or take a breath, that’s when you probably need a comma. + +#### Hyphens +✅ **Do** use a hyphen to indicate a range: +- Monday-Friday + +✅ **Do** use a hyphen for compound modifiers. This is when 2 or more words function as one adjective. Compound modifiers precede the noun they modify: +- We release Fleet on a three-week cadence. +- Osquery is an open-source agent. + +❌ **Don’t** use a hyphen when modifying words follow the noun: +- Fleet is released every three weeks. +- Osquery is open source. + +#### Colons +Colons introduce one or more elements that add detail to the idea before the colon. + +✅ **Do** use a colon to introduce a list: +- The Fleet product has 4 interfaces: Fleet UI, REST API, fleetctl CLI, and Fleet Desktop. + +✅ **Do** use a colon to introduce a phrase (Only capitalize the first word following a colon if it’s a proper noun): +- Introducing Sandbox: the fastest way to play with Fleet. + +#### Exclamation points +They’re fun! But too many can undermine your credibility!!!1! Please use them sparingly. Take context into consideration. And only use one at a time. + +#### Abbreviations and acronyms +If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it and specify the abbreviation in parentheses. + +Then use the short version for all other references. +- A command-line interface (CLI) is a text-based user interface (UI) used to run programs, manage computer files, and interact with the computer. +- The Fleet CLI is called fleetctl. +If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out). + +### Numbers and times + +#### Numbers +Spell out a number when it begins a sentence. Otherwise, use the numeral. + +Sometimes numerals seem out of place. If an expression typically spells out the number, leave it as is: +- First impression +- Third-party integration +- All-in-one platform +Numbers over 3 digits get commas: +- 999 +- 1,000 +- 150,000 + +#### Times +Use numerals and am or pm without a space in between: +- 7am +- 7:30pm +Use a hyphen between times to indicate a time period: +- 7am–10:30pm + +We have users and Fleeties all over the world.🌎 Specify time zones when scheduling events or meetings. + +Abbreviate time zones within the continental United States as follows: +- Eastern time: ET +- Central time: CT +- Mountain time: MT +- Pacific time: PT + +Spell out international time zones: +- Central European Time +- Japan Standard Time + +### Emphasis +- **Bold:** Use bold text to emphasize words or phrases. Just don’t overdo it. Too much bold text may make it hard to see what’s really important. + +- _Italics:_ Use italics when referencing UI elements (e.g., buttons and navigation labels): + - On the settings page, go to *Organization Settings* and select *Fleet Desktop*. + +### Lists +Lists help readers scan content for essential information. They should be as concise and symmetrical as possible. +If you find your list running long, or if each item contains several sentences, you may want to reconsider whether a list is the best approach. +Use a numbered list if it follows a specific order or includes a set number of items. Otherwise, use bullet points. + +#### How to introduce a list +✅ **Do** use a colon if you introduce a list with a complete sentence. + +❌ **Don’t** use a colon if you start a list right after a heading. + +#### How to use end punctuation with list items +End punctuation refers to punctuation marks that are used to end sentences, such as periods, question marks, and exclamation points. + +✅ **Do** use end punctuation if your list items are complete sentences: +- Project confidence and be informative. +- Educate users about security threats positively. +- We never use fear as a marketing tactic. + +❌ **Don’t** use end punctuation if your list items are sentence fragments, single words, or short phrases: +- Policies +- Enterprise support +- Self-hosted agent auto-updates + +❌ **Don’t** mix complete sentences with sentence fragments, single words, or short phrases. Consistent formatting makes lists easier to read. + +❌ **Don’t** use commas or semicolons to end bullet points. + +#### How to capitalize list items +✅ **Do** use a capital letter at the beginning of every bullet point. The only exceptions are words that follow specific style guides (e.g., macOS). + +### Web elements + +#### SQL statements + +When adding SQL statements, all SQL reserved words should be uppercase, and all identifiers (such as tables and columns) should be lowercase. Here’s an example: + +`SELECT days, hours, total_seconds FROM uptime;` + + +## Writing in Fleet-flavored Markdown + +Markdown is a simple formatting syntax used to write content on the web. In order to publish content like [docs](https://fleetdm.com/docs), [handbook entries](https://fleetdm.com/handbook), and [articles](https://fleetdm.com/articles), you must format your content in Markdown. + +### Headings +Try to stay within three or four heading levels. Complicated documents may use more, but pages with a simpler structure are easier to read. +| Markdown | Rendered heading | +|:--------------------|:-----------------------------| +| `# Heading 1` |

Heading 1

| +| `## Heading 2` |

Heading 2

| +| `### Heading 3` |

Heading 3

| +| `#### Heading 4` |

Heading 4

| + +### Emphasis +| Markdown | Rendered text | +|:--------------------|:-----------------------------| +| `**Bold**` | Bold | +| `*Italic*` | Italic | +| `***Bold italic***` | Bold italic | +| `~~Strikethrough~~` | Strikethrough | + +### Line breaks and new lines +Any time you need to add a line break in Markdown, you should add a new line. It is vital to make sure paragraphs are separated by new lines. Otherwise, they will render as the same HTML element. + +For example, if you were adding this section: + +``` +line one +line two +``` + +The Markdown would render on the Fleet website as + +line one +line two + +To make sure formatting is consistent across GitHub and the Fleet website, you need to add a new line anywhere you want a line break. For example, if we separate the lines with a new line: + +``` +line one + +line two +``` + +The Markdown will render correctly as + +line one + +line two + +## Lists + +### Ordered lists +| Markdown | Rendered list | +|:-------------|:-----------------------------| +| 
1. Line one
2. Line two  
3. Line three
4. Line four
| 1. Line one
2. Line two
3. Line three
4. Line four | +| 
1. Line one
1. Indent one
2. Line two
3. Line three
1. Indent one
2. Indent two
4. Line four
| 1. Line one
 1. Indent one
2. Line two
3. Line three
 1. Indent one
 2. Indent two
4. Line four | + +Content nested within an ordered list needs to be indented. If the list is not formatted correctly, the number will reset on each list item, as shown in the example below. + +**Markdown:** + +``` +1. Item one + +Paragraph about item one + +2. Item two +``` + +**Rendered output:** + +1. Item one + +Paragraph about item one + +2. Item two + +To make sure that ordered lists increment correctly, you can indent the content nested within the list. For example, the same ordered list with indentation: + +**Markdown:** + +``` +1. Item one + + Paragraph about item one + +2. Item two +``` + +**Rendered output:** + +1. Item one + + Paragraph about item one + +2. Item two + +### Unordered lists +| Markdown | Rendered list | +|:-------------|:-----------------------------| +| 
- Line one
- Line two  
- Line three
- Line four
| - Line one
- Line two
- Line three
- Line four | +| 
- Line one
 - Indent one
- Line two
- Line three
 - Indent one
 - Indent two
- Line four
| - Line one
 - Indent one
- Line two
- Line three
 - Indent one
 - Indent two
- Line four | + +### Links +The Fleet website currently supports the following Markdown link types. + +#### Inline link +It's a classic. +- **Markdown:** `[This is an inline link](https://domain.com/example.md)` +- **Rendered output:** [This is an inline link](https://domain.com/example.md) + +#### Link with a tooltip +Adding a tooltip to your link is a great way to provide additional information. +- **Markdown:** `[This is link with a tooltip](https://domain.com/example.md "You're awesome!")` +- **Rendered output:** [This is link with a tooltip](https://domain.com/example.md "You're awesome!") + +### URLs +Add angle brackets "< >" around a URL to turn it into a link. +- **Markdown:** `` +- **Rendered output:** + +### Emails +To create a mailto link... oh wait, I'm not going to tell you. +- ***Important: To avoid spam, we **NEVER** use mailto links.*** + +### Tables +To create a table, start with the header by separating rows with pipes (" | "). +Use dashes (at least 3) to separate the header, and add colons to align the text in the table columns. + +- **Markdown:** +``` +| Category one | Category two | Category three | +|:---|---:|:---:| +| Left alignment | Right alignment | Center Alignment | +``` + +- **Rendered output:** + +| Category one | Category two | Category three | +|:---|---:|:---:| +| Left alignment | Right alignment | Center Alignment | + +### Blockquotes +To add a tip blockquote, start a line with ">" and end the blockquote with a blank newline. + +#### Tip blockquotes +Tip blockquotes are the default blockquote style in our Markdown content. + +- **Markdown:** +``` +> This is a tip blockquote. +This line is rendered inside of the tip blockquote. + +This line is rendered outside of the tip blockquote. +``` + +- **Rendered output:** +> This is a tip blockquote. +This line is rendered inside of the tip blockquote. + +This line is rendered outside of the tip blockquote. + +#### Quote blockquotes +To add a quote blockquote, add a `
` HTML element with `purpose="quote"`. + +- **Markdown:** +``` +
+This is a quote blockquote. + +Lines seperated by a blank newline will be rendered on a different line in the blockquote. +
+``` + +- **Rendered output:** +
+This is a quote blockquote. + +Lines seperated by a blank newline will be rendered on a different line in the blockquote. +
+ +#### Large quote blockquote + +You can add a large quote blockquote by adding a `
` HTML element with `purpose="large-quote"`. + +- **Markdown:** +``` +
+This is a large blockquote. + +You can use a large quote blockquote to reduce the font size and line height of the rendered text. +
+``` + +- **Rendered output:** +
+This is a large blockquote. + +You can use a large quote blockquote to reduce the font size and line height of the rendered text. +
+ +#### Mermaid diagrams + +The Fleet Docs support diagrams that are written in mermaid.js syntax. Take a look at the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/README) to learn about the syntax language and what types of diagrams you can display. + +To add a mermaid diagram to the docs, you need to add a code block and specify that it is written in the mermaid language by adding `mermaid` to the opening backticks (i.e., ` ```mermaid`). + +For example, the following code block is a mermaid diagram that has **not** been specified as a mermaid code block: + +``` +graph TD; + A-->D + B-->D + C-->D + D-->E +``` + +Once we specify the `mermaid` as the language in the code block, it will render as a mermaid diagram on fleetdm.com and GitHub. + +```mermaid +graph TD; + A-->D + B-->D + C-->D + D-->E +``` + +If the mermaid syntax is incorrect, the diagram will be replaced with an image displaying an error, as shown in the following example where the code block was written with **intentional** syntax errors: + +```mermaid +graph TD; + A--D +``` +## Website + +This page details processes related to maintaining and updating the Fleet website ([fleetdm.com](https://fleetdm.com)). + +Website-related topics that are NOT included on this page: +- [Publishing an article](https://fleetdm.com/handbook/marketing/how-to-submit-and-publish-an-article) + +### Responsibilities + +The [website group](https://fleetdm.com/handbook/company/product-groups#website-group) is responsible for production and maintenance of the Fleet website. + +### Website Rituals +| Ritual | Frequency | Description | DRI | +|:-----------------------------|:-------------------------|:----------------------------------------------------|-------------------| +| Generate latest schema | once every 3 weeks | After each sprint, generate the latest tables json file to incorporate any new schema documentation. | Eric Shaw | + + +### Website roadmap + +View planned changes to the website on the website group's [sprint board](https://app.zenhub.com/workspaces/g-website-6451748b4eb15200131d4bab/board?sprints=none). + +### Requesting changes + +See Marketing [intake](https://fleetdm.com/handbook/marketing#intake) for more information on how the website team prioritizes new requests. Bugs are always prioritized first. + +### Wireframes + +Before committing anything to code, we create wireframes (referred to as ["drafting"](https://fleetdm.com/handbook/company/development-groups#making-changes)) to illustrate all changes that affect the layout and structure of the user interface, design, or APIs of fleetdm.com. + +See [Why do we use a wireframe first approach](https://fleetdm.com/handbook/company/why-this-way#why-do-we-use-a-wireframe-first-approach) for more information. + +### Design reviews + +We hold regular design review sessions to evaluate, revise, and approve wireframes before moving into production. + +Design review sessions are hosted by [Mike Thomas](https://calendar.google.com/calendar/u/0?cid=bXRob21hc0BmbGVldGRtLmNvbQ) and typically take place daily, late afternoon (CST). Anyone is welcome to join. + +### Estimation sessions + +We use estimation sessions to estimate the effort required to complete a prioritized task. + +Through these sessions, we can: + +- Confirm that wireframes are complete before moving to production. +- Consider all edge cases and requirements that may have been with during wireframing. +- Avoid having the engineer make choices for “unknowns” during production. +- More accurately plan and prioritize upcoming tasks. + +#### Story points + +Story points represent the effort required to complete a task. After accessing wireframes, we typically play planning poker, a gamified estimation technique, to determine the necessary story point value. + +We use the following story points to estimate website tasks: + +| Story point | Time | +|:---|:---| +| 1 | 1 to 2 hours | +| 2 | 2 to 4 hours | +| 3 | 1 day | +| 5 | 1 to 2 days | +| 8 | Up to a week | +| 13 | 1 to 2 weeks | + +### Quality + +Quality assurance (QA) checks must be completed before changes to the website can be merged. Read on to learn about the quality assurance process for the website. + +> **Important:** A PR to the website should not be merged until the quality assurance process has been successfully completed. + +#### Manual QA + +The product manager of the website group is responsible for making sure that manual QA steps have been added to requests. + +#### Writing QA steps + +QA steps are step-by-step instructions used to confirm that changed to the website function as expected. They should be simple and clear enough for anybody to follow. Example steps are included in [the “Website request” issue template](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=%23g-website&template=website-request.md&title=Request%3A+__________________________). + +#### Actioning QA steps + +[View the website locally](#test-changes-to-the-website) and follow the QA steps in the request ticket to test changes. + +QA steps should be actioned when a request has been moved into the “Review/QA” column of the website product board. PRs to the website should not be merged until QA has been completed. + +A successful QA check can be indicated by leaving a comment in the conversation thread of the PR. + +#### Additional QA + +In addition to the steps above. All website changes must be thoroughly checked at all breakpoints and a [browser compatibility](#browser-compatibility) test should be carried out on [supported browsers](https://fleetdm.com/docs/using-fleet/supported-browsers) before website changes can go live. + +### Testing changes + +When making changes to the Fleet website, you can test your changes by running the website locally. To do this, you'll need the following: + +- A local copy of the [Fleet repo](https://github.com/fleetdm/fleet). +- [Node.js](https://nodejs.org/en/download/) +- (Optional) [Sails.js](https://sailsjs.com/) installed globally on your machine (`npm install sails -g`) + +Once you have the above follow these steps: + +1. Open your terminal program, and navigate to the `website/` folder of your local copy of the Fleet repo. + + > Note: If this is your first time running this script, you will need to run `npm install` inside of the website/ folder to install the website's dependencies. + + +2. Run the `build-static-content` script to generate HTML pages from our Markdown and YAML content. + - **With Node**, you will need to use `node ./node_modules/sails/bin/sails run build-static-content` to execute the script. + - **With Sails.js installed globally** you can use `sails run build-static-content` to execute the script. + + > You can use the `--skipGithubRequests` flag to skip requests made to GitHub if you get rate-limited by GitHub’s API while running this script. + > + > e.g., `node ./node_modules/sails/bin/sails run build-static-content --skipGithubRequests` + +3. Once the script is complete, start the website server. From the `website/` folder: + - **With Node.js:** start the server by running `node ./node_modules/sails/bin/sails lift` + - **With Sails.js installed globally:** start the server by running `sails lift`. +4. When the server has started, the Fleet website will be availible at [http://localhost:2024](http://localhost:2024) + + > **Note:** Some features, such as Fleet Sandbox, Self-service license dispenser, and account creation are not availible when running the website locally. If you need help testing features on a local copy, reach out to `@eashaw` in the [#g-website](https://fleetdm.slack.com/archives/C058S8PFSK0) channel on Slack.. + + +#### 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](https://heroku.com) 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. + +### 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). + +- 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 them for fixing. +- If in doubt about anything regarding design or layout, please reach out to the Design team. + +### Error handling + +#### 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. + +#### Incident post-mortems + +When conducting an incident post-mortem, answer the following three questions: + +1. Impact: What impact did this error have? How many humans experienced this error, if any, and who were they? +2. Root Cause: Why did this error happen? +3. Side effects: did this error have any side effects? e.g., did it corrupt any data? Did code that was supposed to run afterward and “finish something up” not run, and did it leave anything in the database or other systems in a broken state requiring repair? This typically involves checking the line in the source code that threw the error. + +### Vulnerability monitoring + +Every week, we run `npm audit --only=prod` to check for vulnerabilities on the production dependencies of fleetdm.com. Once we have a solution to configure GitHub's Dependabot to ignore devDependencies, this manual process can be replaced with Dependabot. + +### Experimentation + +In order for marketing to iterate rapidly we have created a process of experimentation. This will allow a small group of marketers to draft, review and publish a page or a flyer or an experiment without getting a series of approvals. Experiments should be short-lived, temporary things intended for a small audience. When an experiment succeeds it should immediately be turned into a part of Fleet'd rituals and then go through the proper wireframe-first approach. + +Website experiments and landing pages should live behind `/imagine` url. Which is hidden from the sitemap and intended to be linked to from ads and marketing campaigns. Design experiments (flyers, swag, etc.) should be limited to small audiences (less than 500 people) to avoid damaging the brand or confusing our customers. In general, experiments that are of a design nature should be targeted at prospects and random users, never targeted at our customers. + +Some examples of experiments that would qualify to get a rapid approach: +- A flyer for a meetup "Free shirt to the person who can solve this riddle!" +- A landing page for a movie screening presented by Fleet +- A landing page for a private event +- A landing page for an ad campaign that is running for 4 weeks. +- An A/B test on product positioning +- A giveaway page for a conference +- Table-top signage for a conference booth or meetup + +#### Landing pages + +The Fleet website has a built-in landing page generator that can be used to quickly create a new page that lives under the /imagine/ url. + +To generate a new page, you'll need: + +- A local copy of the [Fleet repo](https://github.com/fleetdm/fleet). +- [Node.js](https://nodejs.org/en/download/) +- (Optional) [Sails.js](https://sailsjs.com/) installed globally on your machine (`npm install sails -g`) + +1. Open your terminal program, and navigate to the `website/` folder of your local copy of the Fleet repo. + + > Note: If this is your first time running the website locally, you will need to run `npm install` inside of the website/ folder to install the website's dependencies. + +2. Call the `landing-page` generator by running `node ./node_modules/sails/bin/sails generate landing-page [page-name]`, replacing `[page-name]` with the kebab-cased name (words seperated by dashes `-`) of your page. + +3. After the files have been generated, you'll need to manually update the website's routes. To do this, copy and paste the generated route for the new page to the "Imagine" section of `website/config/routes.js`. + +4. Next you need to update the stylesheets so that the page can inherit the correct styles. To do this, copy and paste the generated import statement to the "Imagine" section of `website/assets/styles/importer.less`. + +5. Start the website by running `node ./node_modules/sails/bin/sails lift` (or `sails lift` if you have Sails installed globally). The new landing page will be availible at `http://localhost:1337/imagine/{page-name}`. + +6. Replace the lorum ipsum and placeholder images on the generated page with the page's real content, and add a meta description and title by changing the `pageTitleForMeta` and `pageDescriptionForMeta in the page's `locals` in `website/config/routes.js`. + + +### 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. + +### Website services + +#### Cloudflare + +We use Cloudflare to manage the DNS records of fleetdm.com and our other domains. Cloudflare offers a free, user-friendly, and cloud-agnostic interface that allows authorized team members to manage all our domains easily. +If you need access to Fleet's Cloudflare account, please ask the [DRI](https://fleetdm.com/handbook/company/why-this-way#why-direct-responsibility) Zach Wasserman in Slack for an invitation. + + +To make DNS changes in Cloudflare: +1. Log into your Cloudflare account and select the "Fleet" account. +2. Select the domain you want to change and go to the DNS panel on that domain's dashboard. +3. To add a record, click the "Add record" button, select the record's type, fill in the required values, and click "Save". If you're making changes to an existing record, you only need to click on the record, update the record's values, and save your changes. + +#### Heroku + +TODO: Document. + +#### Algolia + +TODO: Document. + +### Docs + +This page details processes related to maintaining and updating the ([Fleet docs](https://fleetdm.com/docs)). + +When someone asks a question in a public channel, it's safe to assume they aren't the only person looking for an answer. + +To make our docs as helpful as possible, the Community team gathers these questions and uses them to make a weekly documentation update. + +Fleet's goal is to answer every question with a link to the docs and/or result in a documentation update. + +#### Documentation DRIs + +TODO: Document. + +#### Tracking + +When responding to a question or issue in the [#fleet](https://osquery.slack.com/join/shared_invite/zt-h29zm0gk-s2DBtGUTW4CFel0f0IjTEw#/) channel of the osquery Slack workspace, push the thread to Zapier using the `TODO: Update docs` Zap. This will add information about the thread to the [Slack Questions Spreadsheet](https://docs.google.com/spreadsheets/d/15AgmjlnV4oRW5m94N5q7DjeBBix8MANV9XLWRktMDGE/edit#gid=336721544). In the `Notes` field, you can include any information that you think will be helpful when making weekly doc updates. That may be something like + +- proposed change to the documentation. +- documentation link that was sent as a response. +- link to associated thread in [#help-oncall](https://fleetdm.slack.com/archives/C024DGVCABZ). +- **Note:** When submitting any pull request that changes Markdown files in the docs, request an editor review from Kathy Satterlee, who will escalate to the [on-call engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) as needed. + + ## Vision for dept handbook pages The idea here is to get this vision implemented on a single departmental handbook page first, starting with handbook/company/ceo. It's hard to know what the philosophy should be until we can see it. So we need to shorten the feedback loop so we can see it change live in one place. That way we can iterate in one place instead of having things go a bunch of different directions, and adding in all the complexity of extra redirects to keep track of and all that stuff. Then once we've got that looking good and have iterated a bit, we'll spread it out. @@ -32,116 +943,72 @@ Another thing is that we need to get a better intuitive understanding of who the - (h2) Slack channels +## Commonly used terms -## Meetings - -Plan to join meetings on time. At Fleet, we start on time and do not wait for folks to join. -Our meetings are conducted over zoom, please join with a working microphone and with your camera on whenever possible. -Being even a few minutes late can make a big difference and slow your meeting counterparts down. When in doubt, show up a couple of minutes early. - -Spend the first few minutes of a meeting being present and making small talk. -Since we are all remote, it's easy to miss out on hallway chatter and human connections that happen in [meatspace](https://www.dictionary.com/browse/meatspace). -Use this time together during the first minute to say "Hi!" Then you can jump into the topics to be discussed. - -Turning on your camera allows for more complete and intuitive verbal and non-verbal communication. -Feel free to leave your camera on or turn it off when joining meetings with new participants you might not be familiar with yet. Turn your camera on when you lead or cohost a meeting. -In an all-remote company, “face time” matters. - -***Before scheduling a meeting*** ask yourself: - -1. Can this information be presented [async](https://fleetdm.com/handbook/company/why-this-way#why-handbook-first-strategy)? - - - Is there another way to distribute this info or align on a course of action that _doesn't_ take valuable time away from customers, projects, or personal time? Could you create a [Google Doc](https://docs.google.com/document/d/1TaZ654gTwadWGDYhP3zuAzWe0eiY0s9NhaU9KLCokgw/edit) and share it with would-be attendees? If the info can be documented it should be. Could the info be sent in Slack or by email? - -2. Do I have all the information needed to schedule this meeting? - -TODO - - -### Internal meeting scheduling - -Fleet uses the Zoom add-on for Google Calendar to schedule meetings (exceptions are customers that are non-negotiably required to use a different tool) when we [create calendar events](https://support.google.com/calendar/answer/72143?hl=en&ref_topic=10510646&sjid=7187599067132459840-NA#zippy=%2Cclick-an-empty-time-in-your-calendar). -Our Zoom meetings are configured to let participants join before the host arrives, to make sure meetings start on time even if the host isn't there. - -To schedule a meeting within Fleet: -- To add a Zoom meeting to a calendar event, click the "Add video conferencing" dropdown and select "Zoom Meeting." Google Calendar will automatically add the Zoom meeting details and instructions to join the event. -- Enter the `@fleetdm.com` emails for each participant into the "Add guests" box in Google Calendar, and the calendar availability for each participant will appear in your view. -- Select a meeting time, the participants will automatically be invited and a video conference will be attached to the invite (this can save a lot of communication overhead when scheduling with multiple participants). - -It is important to [set your workinghours](https://support.google.com/calendar/answer/7638168?hl=en&co=GENIE.Platform%3DDesktop) in Google Calendar and block out any personal time/events/PTO, so that team members do not inadvertently schedule a time when you are not available. -- Many team members use the free tier of [reclaim.ai](https://reclaim.ai/) to synchronize personal event times (without event details) into their work calendars. -It is also common practice to block out time for focused work. - -### Modifying an event organized by someone else - -To edit an event where someone else at Fleet is the organizer, you can first subscribe to their calendar in Google Calendar and then edit the event on their calendar. Your edits will automatically apply to all attendees. -This works because every Fleetie grants edit access to everyone else at Fleet as part of onboarding. - -### External meeting scheduling - -When scheduling external meetings, provide external participants with a -[Calendly](https://calendly.com) link to schedule with the relevant internal participants. If you -need a Calendly account, reach out to `mikermcneil` via Slack. - - -## Email relays - -There are several special email addresses that automatically relay messages to the appropriate people at Fleet. Each email address meets a minimum response time ("Min RT"), expressed in business hours/days, and has a dedicated, directly responsible individual (DRI) who is responsible for reading and replying to emails sent to that address. You can see a list of those email addresses in ["Contacting Fleet" (private Google doc)](https://docs.google.com/document/d/1tE-NpNfw1icmU2MjYuBRib0VWBPVAdmq4NiCrpuI0F0/edit#). - - -## Github - -### GitHub labels - -We use special characters to define different types of GitHub labels. By combining labels, we -organize and categorize GitHub issues. This reduces the total number of labels required while -maintaining an expressive labeling system. For example, instead of a label called -`platform-dev-backend`, we use `#platform :dev ~backend`. - -| Special character | Label type | Examples | -|:------------------|:------------|:------------------------------------| -| `#` | Noun | `#platform`, `#interface`, `#agent` -| `:` | Verb | `:dev`, `:research`, `:design` -| `~` | Adjective | `~blocked`, `~frontend`, `~backend` - - -## Zoom - -We use [Zoom](https://zoom.us) for virtual meetings at Fleet, and it is important that every team member feels comfortable hosting, joining, and scheduling Zoom meetings. -By default, Zoom settings are the same for all Fleet team members, but you can change your personal settings on your [profile settings](https://zoom.us/profile/setting) page. -Settings that have a lock icon next to them have been locked by an administrator and cannot be changed. Zoom administrators can change settings for all team members on the [account settings page](https://zoom.us/account/setting) or for individual accounts on the [user management page](https://zoom.us/account/user#/). - - -## Slack - -At Fleet, we do not send internal emails to each other. Instead, we prefer to use [Slack](https://www.linkedin.com/pulse/remote-work-how-set-boundaries-when-office-your-house-lora-vaughn/) to communicate with other folks who work at Fleet. -We use threads in Slack as much as possible. Threads help limit noise for other people following the channel and reduce notification overload. -We configure our [working hours in Slack](https://slack.com/help/articles/360025054173-Set-up-Slack-for-work-hours-) to make sure everyone knows when they can get in touch with others. - -### Slack channel prefixes -We have specific channels for various topics, but we also have more general channels for the teams at Fleet. -We use these prefixes to organize the Fleet Slack: - * ***g-***: for team/group channels *(Note: "g-" is short for "grupo" or "group")*. - * ***oooh-***: used to discuss and share interesting information about a topic. - * ***help-***: for asking for help on specific topics. - * ***at*** or ***fleet-at***: for customer channels. - * ***2023-***: for temporary channels _(Note: specify the relevant year in four digits, like "YYYY-`)_ - -#### Slack communications and best practices -In consideration of our team, Fleet avoids using global tags in channels (i.e. @here, @channel, etc). - 1. What about polls? Good question, Fleeties are asked to post their poll in the channel and @mention the teammates they would like to hear from. - 2. Why does this matter? Great question! The Fleet [culture](https://fleetdm.com/handbook/company#culture) is pretty simple: think of others, and remember the company [Values](https://fleetdm.com/handbook/company#values). - - - - -## Levels of confidentiality - -- *Public* _(share with anyone, anywhere in the world)_ -- *Confidential* _(share only with team members who've signed an NDA, consulting agreement, or employment agreement)_ -- *Classified* _(share only with founders of Fleet, business operations, and/or the people involved. e.g., US social security numbers during hiring)_ - +This glossary provides definitions to commonly used terms within our space. +| Term | Meaning | +|:------ |:-----------------| +| **antivirus** | A class of programs designed to detect, block, and clear away malware from devices, networks, and IT systems. | +| **API** | (Application Programming Interface) a software go-between that allows applications to communicate. | +| **automation** | A system that operates without needing intervention from a human to do so. | +| **AWS** | (Amazon Web Services) An ever-evolving cloud computing platform designed to allow application providers, ISVs, and vendors to host applications. | +| **CI/CD** | (Continuous Integration and Continuous Delivery/Continuous Deployment) A software development practice where cumulative code changes are made regularly and accurately. | +| **CLI** | (Command Line Interface) A tool for managing Fleet from the command line. | +| **Client Platform Engineer (CPE)** | See: CPE. | +| **cloud** | Data storage, networking, servers, databases, software, intelligence, and analytics through the internet instead of a device's hard drive. | +| **command line** | A horizontal row on an interface for text to allow you to type in a variety of commands. Also, see "CLI." | +| **compliance** | The act of being in line with the established risk-based expectations to preserve the strength and confidentiality of data stored, used, and transmitted. | +| **CPE** | (Client Platform Engineer) A person who constructs, evaluates, and deploys solutions to administrate a fleet of "clients" or end-users and does so in a scaleable manner. | +| **CVE** | (Common Vulnerabilities and Exposures) A system that provides a technique for sharing information publicly. | +| **data leaks** | When crucial and confidential data is unwittingly exposed physically, on the Internet, or any other way. This includes misplaced hard drives or devices. | +| **device management** | The process of overseeing the execution, process, and upkeep of a device, be it physical or virtual. | +| **DevOps** | Practices that incorporate both software development (Dev) and IT operations (Ops). | +| **Docker** | An open source platform that allows one to manage containerized applications. | +| **DRI** | The person who is singularly responsible for a given aspect of the open source project, the product, or the company. | +| **EDR** | (Endpoint Detection and Response) Security software that continually audits end-user devices to identify and respond to threats such as malware and ransomware. Also, see EDTR. | +| **EDTR** | (Endpoint Detection and Threat Response) Security software that continually audits end-user devices to identify and respond to threats such as malware and ransomware. Also, see EDR. | +| **encryption** | The act of converting data into a cipher that requires a key to be deciphered. | +| **end-users** | Someone using a distributed device or service. This could be a computer or a mobile device. | +| **FileVault** | The macOS feature to encrypt entire drives. | +| **Firewall** | A device or software that is used to block unwanted network traffic. | +| **fleetctl** | A CLI tool for managing Fleet from the command line. It can be used to accomplish many tasks you would typically need to do through the UI (User Interface). Also, fleetctl enables a GitOps workflow with Fleet and osquery. | +| **GitHub** | Cloud-based service for software development and version control using Git. | +| **historical compliance** | The ability to view past behavior around established risk-based controls to safeguard the integrity, confidentiality, and access of data storage, processing, or transfers. | +| **IETF** | (Internet Engineering Task Force) An organization that defines standardizing operations of internet protocols | +| **Internet Engineering Task Force (IETF)** | See: IETF | +| **IR** | (Incident Response) The actions one takes in response to a security breach or cyberattack. | +| **Linux** | An open source operating system. | +| **Logica** | An IT and management consultancy company based in the United Kingdom. | +| **macOS** | The operating system used in all of Apple's Mac computers. | +| **Munki** | Open-source software deployment tool for macOS. | +| **open core** | Is the business model where a company has a core version of a product with some of the features as (FOSS) Free Open Source Software in addition to a paid commercial version that is proprietary software. | +| **open source** | Software with intentionally public code for the sake of transparency. | +| **OS** | (Operating System) Software that provides the groundwork and instructions for a device's basic functions, including application use and controlling peripherals. | +| **osquery** | A tool that assembles low-level operating system analytics and monitoring. | +| **out-of-policy device** | A device that is fails any security or vulnerability policy created in Fleet. | +| **permissions** | Users have different abilities depending on the access level they have. | +| **platform** | Any software or hardware for hosting an application, data, or service. | +| **policies** | Yes or no questions you can ask using Fleet about your host devices. | +| **policy compliance** | The state of whether a device is passing or failing policies created in Fleet. | +| **queries** | Questions you can ask an end-user device's operating system via Fleet. | +| **SAML** | (Security Assertion Markup Language) A standard that allows identity providers (IdP) to authorize credentials for service providers; enabling SSO (Single Sign-On). | +| **security audits** | An assessment of an organization's security posture. | +| **security engineer** | Individual for managing and implementing security systems in an organization. | +| **SIEM** | (Security Information and Event Management) Technology that assembles data, security warnings, and events into one platform and provides almost real-time analyzed data to help you better monitor your organization's security. | +| **Site Reliability Engineers (SREs)** | Individuals who apply site reliability principles to improve reliability and scalability of systems in a systematic manner. | +| **SQL** | (Structured Query Language) A language used to manage databases and complete a variety of operations tasks within said databases. | +| **SRE** | See "Site Reliabilty Engineers." | +| **SSO authentication** | (Single Sign-On authentication) Allows identity providers (IdP) to authorize credentials for service providers once and use that as the authentication for multiple outside accounts. | +| **TLS** | (Transport Layer Security) An Internet Engineering Task Force (IETF) standardized protocol that authenticates and provides privacy and data protection over computer networks. | +| **token** | A physical Two-Factor Authentication (2FA) login security device to prove one's identity. | +| **Transport Layer Security (TLS)** | See: TLS | +| **UI** | (User Interface) An interactive space in a program that concentrates on style and intuitive use. | +| **URL** | Uniform resource locator. Specifies where a web resource is located (ex: https://fleetdm.com/articles/) | +| **vulnerabilities** | An exploitable weakness that can lead to unauthorized access or other negative consequences to a computer system. | +| **Windows** | Microsoft's graphical operating system. | +| **YAML** | A data serialized language that has features derived from Perl, C, HTML, and other languages and is often used to write configuration files. | - + diff --git a/handbook/marketing/README.md b/handbook/marketing/README.md index 306dd11c0..9385a7ffe 100644 --- a/handbook/marketing/README.md +++ b/handbook/marketing/README.md @@ -305,9 +305,6 @@ See [📖Product#Working with Figma](https://fleetdm.com/handbook/product#workin **Marketing assets.** Product screenshots and artwork for social media, articles, and other marketing assets can be found in [Collateral](https://www.figma.com/files/project/20798819). -### Content style guide - -Learn how to communicate as Fleet with guidelines for tone of voice, our approach, grammar and mechanics, and more. [Read the content style guide](./content-style-guide). ### Publishing Fleet content @@ -348,13 +345,35 @@ Detail the minimum time needed for new or updated content to be live (published) | YouTube | **Queued** – see _(TODO: Publishing on YouTube as Fleet.)_ | **Absorb** for revisions to the description. **Pair** or **absorb** for video content (pair if possible otherwise, silently fix ASAP by deleting the post. Consider that the video may also have been promoted on social media – see Social media (Twitter, FB, LinkedIn) above. | three business days | | Decks | **Instant**. Sales typically creates decks. The Brand team shouldn't be a blocker. | **Feedback** | three business days | -### For editors -Check the [Editor's page](./editor-guide) for everything you need to know to reach editor bliss at Fleet. +#### How to edit Markdown pull requests for the docs + +- When someone creates a pull request for a doc that affects Markdown files, they’ll need to request a review from the editor. +- If no edits are needed, the editor will merge the PR. +- If an edit changes the meaning, or if unsure, the editor should request a review from the [on-call engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) and remove themselves as a reviewer. + +#### How to edit articles, release posts, and press releases + +Editing articles, release posts, and press releases usually comes in three flavors: a Google Docs draft, a new pull request, or an edit to an existing article. + +* For unpublished articles, please read the review process in [How to submit and publish an article](https://fleetdm.com/handbook/marketing/how-to-submit-and-publish-an-article#review-process). + +* To edit an existing article, see [How to make edits with GitHub](#how-to-make-edits-with-github). + +#### 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. + +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-marketing Slack channel and tag the Brand team 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 Marketing team to include and re-post. + ### Commonly used terms -If you find yourself feeling a little overwhelmed by all the industry terms within our space, or if you just need to look something up, our glossary of [commonly used terms](./commonly-used-terms) is here to help. +If you find yourself feeling a little overwhelmed by all the industry terms within our space, or if you just need to look something up, our glossary of [commonly used terms](https://fleetdm.com/handbook/company/communications#commonly-used-terms) is here to help. ### Email blasts @@ -420,9 +439,6 @@ Once you have the above follow these steps: Read the [Website handbook](./website-handbook) for detailed information and processes specific to the Fleet website. Including the website roadmap, how to request changes, and processes related to QA, deploying changes, and marketing experimentation. -## Documentation - -The [Docs handbook](./docs-handbook) details processes specific to updating and maintaining the Fleet docs. ## Rituals @@ -439,10 +455,10 @@ The following table lists the Marketing, Brand, and Community group's rituals, f | Enrich Salesforce leads | Weekly | Follow the Salesforce lead enrichment process every Friday | Drew Baker | | Outside contributions | Weekly | Check pull requests for outside contributions every Monday | Drew Baker| | Weekly article | Weekly | Publish an article and promote it on social media | Drew Baker| -| Weekly ins and outs | Weekly | Track marketing team ins and outs | Jarod Reyes | +| Weekly ins and outs | Weekly | Track marketing team ins and outs | Mike McNeil | | Podcast outreach | Weekly | Conduct podcast outreach twice a week | Drew Baker | | Weekly update | Weekly | Update the marketing KPIs in the ["🌈 Weekly updates" spreadsheet](https://docs.google.com/spreadsheets/d/1Hso0LxqwrRVINCyW_n436bNHmoqhoLhC8bcbvLPOs9A/edit#gid=0) | Drew Baker | -| Update the "Release" field on the #g-marketing board | Every 3 weeks |
  • Go to the [marketing board](https://github.com/orgs/fleetdm/projects/37/views/2)
  • add a 3-week iteration with the correct release number
| Jarod Reyes | +| Update the "Release" field on the #g-marketing board | Every 3 weeks |
  • Go to the [marketing board](https://github.com/orgs/fleetdm/projects/37/views/2)
  • add a 3-week iteration with the correct release number
| Mike McNeil | | Monthly conference checks | Monthly | Check for conference openings and sponsorship opportunities on the 1st of every month | Drew Baker| | Freshen up pinned posts | Quarterly | Swap out or remove pinned posts on the brand Twitter account and LinkedIn company page | Drew Baker | | Tweet review | Daily | Review tweets for tone and brand consistency | Mike Thomas | @@ -481,15 +497,27 @@ These groups maintain the following [Slack channels](https://fleetdm.com/handboo | Slack channel | [DRI](https://fleetdm.com/handbook/company#group-slack-channels) | |:----------------------------|:--------------------------------------------------------------------| -| `#g-marketing` | Jarod Reyes | +| `#g-marketing` | Mike McNeil | | `#g-website` | Michael Thomas | -| `#fleet-mindshare-pr` | Jarod Reyes | -| `#help-public-relations` | Jarod Reyes | -| `#help-promote` | Jarod Reyes | +| `#fleet-mindshare-pr` | Drew Baker | +| `#help-public-relations` | Mike McNeil | +| `#help-promote` | Mike McNeil | | `#help-swag` | Drew Baker | | `#oooh-websites` | Michael Thomas | | `#help-p1` | Mike McNeil | +#### Stubs + +##### Content style guide + +Please see 📖[handbook/company/communications/content-style-guide](https//fleetdm.com/handbook/company/communications/content-style-guide). + +##### Documentation + +Please see 📖[handbook/company/communications/content-style-guide](https//fleetdm.com/handbook/company/communications/content-style-guide). + + + diff --git a/handbook/marketing/commonly-used-terms.md b/handbook/marketing/commonly-used-terms.md deleted file mode 100644 index 51c0c797d..000000000 --- a/handbook/marketing/commonly-used-terms.md +++ /dev/null @@ -1,68 +0,0 @@ -# Commonly used terms - -This glossary provides definitions to commonly used terms within our space. - -| Term | Meaning | -|:------ |:-----------------| -| **antivirus** | A class of programs designed to detect, block, and clear away malware from devices, networks, and IT systems. | -| **API** | (Application Programming Interface) a software go-between that allows applications to communicate. | -| **automation** | A system that operates without needing intervention from a human to do so. | -| **AWS** | (Amazon Web Services) An ever-evolving cloud computing platform designed to allow application providers, ISVs, and vendors to host applications. | -| **CI/CD** | (Continuous Integration and Continuous Delivery/Continuous Deployment) A software development practice where cumulative code changes are made regularly and accurately. | -| **CLI** | (Command Line Interface) A tool for managing Fleet from the command line. | -| **Client Platform Engineer (CPE)** | See: CPE. | -| **cloud** | Data storage, networking, servers, databases, software, intelligence, and analytics through the internet instead of a device's hard drive. | -| **command line** | A horizontal row on an interface for text to allow you to type in a variety of commands. Also, see "CLI." | -| **compliance** | The act of being in line with the established risk-based expectations to preserve the strength and confidentiality of data stored, used, and transmitted. | -| **CPE** | (Client Platform Engineer) A person who constructs, evaluates, and deploys solutions to administrate a fleet of "clients" or end-users and does so in a scaleable manner. | -| **CVE** | (Common Vulnerabilities and Exposures) A system that provides a technique for sharing information publicly. | -| **data leaks** | When crucial and confidential data is unwittingly exposed physically, on the Internet, or any other way. This includes misplaced hard drives or devices. | -| **device management** | The process of overseeing the execution, process, and upkeep of a device, be it physical or virtual. | -| **DevOps** | Practices that incorporate both software development (Dev) and IT operations (Ops). | -| **Docker** | An open source platform that allows one to manage containerized applications. | -| **DRI** | The person who is singularly responsible for a given aspect of the open source project, the product, or the company. | -| **EDR** | (Endpoint Detection and Response) Security software that continually audits end-user devices to identify and respond to threats such as malware and ransomware. Also, see EDTR. | -| **EDTR** | (Endpoint Detection and Threat Response) Security software that continually audits end-user devices to identify and respond to threats such as malware and ransomware. Also, see EDR. | -| **encryption** | The act of converting data into a cipher that requires a key to be deciphered. | -| **end-users** | Someone using a distributed device or service. This could be a computer or a mobile device. | -| **FileVault** | The macOS feature to encrypt entire drives. | -| **Firewall** | A device or software that is used to block unwanted network traffic. | -| **fleetctl** | A CLI tool for managing Fleet from the command line. It can be used to accomplish many tasks you would typically need to do through the UI (User Interface). Also, fleetctl enables a GitOps workflow with Fleet and osquery. | -| **GitHub** | Cloud-based service for software development and version control using Git. | -| **historical compliance** | The ability to view past behavior around established risk-based controls to safeguard the integrity, confidentiality, and access of data storage, processing, or transfers. | -| **IETF** | (Internet Engineering Task Force) An organization that defines standardizing operations of internet protocols | -| **Internet Engineering Task Force (IETF)** | See: IETF | -| **IR** | (Incident Response) The actions one takes in response to a security breach or cyberattack. | -| **Linux** | An open source operating system. | -| **Logica** | An IT and management consultancy company based in the United Kingdom. | -| **macOS** | The operating system used in all of Apple's Mac computers. | -| **Munki** | Open-source software deployment tool for macOS. | -| **open core** | Is the business model where a company has a core version of a product with some of the features as (FOSS) Free Open Source Software in addition to a paid commercial version that is proprietary software. | -| **open source** | Software with intentionally public code for the sake of transparency. | -| **OS** | (Operating System) Software that provides the groundwork and instructions for a device's basic functions, including application use and controlling peripherals. | -| **osquery** | A tool that assembles low-level operating system analytics and monitoring. | -| **out-of-policy device** | A device that is fails any security or vulnerability policy created in Fleet. | -| **permissions** | Users have different abilities depending on the access level they have. | -| **platform** | Any software or hardware for hosting an application, data, or service. | -| **policies** | Yes or no questions you can ask using Fleet about your host devices. | -| **policy compliance** | The state of whether a device is passing or failing policies created in Fleet. | -| **queries** | Questions you can ask an end-user device's operating system via Fleet. | -| **SAML** | (Security Assertion Markup Language) A standard that allows identity providers (IdP) to authorize credentials for service providers; enabling SSO (Single Sign-On). | -| **security audits** | An assessment of an organization's security posture. | -| **security engineer** | Individual for managing and implementing security systems in an organization. | -| **SIEM** | (Security Information and Event Management) Technology that assembles data, security warnings, and events into one platform and provides almost real-time analyzed data to help you better monitor your organization's security. | -| **Site Reliability Engineers (SREs)** | Individuals who apply site reliability principles to improve reliability and scalability of systems in a systematic manner. | -| **SQL** | (Structured Query Language) A language used to manage databases and complete a variety of operations tasks within said databases. | -| **SRE** | See "Site Reliabilty Engineers." | -| **SSO authentication** | (Single Sign-On authentication) Allows identity providers (IdP) to authorize credentials for service providers once and use that as the authentication for multiple outside accounts. | -| **TLS** | (Transport Layer Security) An Internet Engineering Task Force (IETF) standardized protocol that authenticates and provides privacy and data protection over computer networks. | -| **token** | A physical Two-Factor Authentication (2FA) login security device to prove one's identity. | -| **Transport Layer Security (TLS)** | See: TLS | -| **UI** | (User Interface) An interactive space in a program that concentrates on style and intuitive use. | -| **URL** | Uniform resource locator. Specifies where a web resource is located (ex: https://fleetdm.com/articles/) | -| **vulnerabilities** | An exploitable weakness that can lead to unauthorized access or other negative consequences to a computer system. | -| **Windows** | Microsoft's graphical operating system. | -| **YAML** | A data serialized language that has features derived from Perl, C, HTML, and other languages and is often used to write configuration files. | - - - diff --git a/handbook/marketing/content-style-guide.md b/handbook/marketing/content-style-guide.md deleted file mode 100644 index 8e1ed569f..000000000 --- a/handbook/marketing/content-style-guide.md +++ /dev/null @@ -1,317 +0,0 @@ -# Content style guide - -## Tone of voice -- **Clear.** Focus on what matters most. Details can clear things up, but too many are confusing. Use simple words and sentences, especially in technical conversations. -- **Thoughtful.** Try your best to understand the topic and your audience. Choose words carefully. Outdated terms may offend modern readers. -- **Friendly.** Make people feel welcome. Let them know they’re talking to another human who cares. Relate to their struggles and offer solutions. -- **Inspiring.** Empower users with practical advice. Show them what success looks like. Manage risk, not fear. Help people feel confident about handling security threats. - -## Our approach -Every piece of content we write should embody our values. To make sure we succeed, we apply a design thinking approach to our writing by following these steps: - -- **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. Your first pass won’t be perfect. And that’s okay. If it isn’t working, try it again. -- **Test.** Revise, edit, proofread, repeat. Revise, edit, proofread, repeat. Revise, edit... You get the idea. - -### What would Mister Rogers say? -[*Mister Rogers’ Neighborhood*](https://en.wikipedia.org/wiki/Mister_Rogers%27_Neighborhood) was one of the longest-running children’s TV series. That’s thanks to [Fred Rogers](https://en.wikipedia.org/wiki/Fred_Rogers)’ communication skills. He knew kids heard things differently than adults. So, he checked every line to avoid confusion and encourage positivity. - -Our audience is a little older. But just like the show, Mister Rogers’ method is appropriate for all ages. Here are some steps you can take to communicate like Mister Rogers: - -- State the idea you want to express as clearly as possible. -- Rephrase the idea in a positive manner. -- Rephrase the idea, directing your reader to authorities they trust. -- Rephrase the idea to eliminate anything that may not apply to your reader. -- Add a motivational idea that gives your reader a reason to follow your advice. -- Rephrase the new statement, repeating the first step. - -Consider this example tweet. - -- 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. - -What would Mister Rogers say? The tweet could look something like this... - -- Distributed workforces are here to stay. So, it’s a great time to help employees work with your security experts (and not around them). Because stronger teams get to celebrate more victories. - -By Mister Rogersing our writing, we can encourage our readers to succeed by emphasizing optimism. You might not be able to apply all of these steps every time. That’s fine. Think of these as guidelines to help you simplify complex topics. - -### Writing about Fleet - -#### Company, product, and employees -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.” - -Employees are “Fleeties.” - -#### Capitalizing "fleets" - -When talking about a group of devices or virtual servers, use "fleet" or "fleets" (lowercase). When talking about the product or company, use "Fleet" (capitalized). - -#### Capitalizing osquery -Osquery should always be written in lowercase unless used to start a sentence or heading: - -- Open-source software, built on osquery. -- Osquery and Fleet provide structured, convenient access to information about your devices. - -#### Device vs endpoint -When talking about a users' computer, we prefer to use "device" over _endpoint._ Devices in this context can be a physical device or virtual instance that connect to and exchange information with a computer network. Examples of devices include mobile devices, desktop computers, laptop computers, virtual machines, and servers. - - -## Grammar and mechanics - -### Headings -Headings help readers quickly scan content to find what they need. Organize page content using clear headings specific to the topic they describe. - -#### Context -Headings should guide readers through your writing. While our readers are more tech-savvy than most, we can’t expect them to recognize queries by SQL alone. - -Avoid using code for headings. Instead, say what the code does and include code examples in the body of your document. - -#### Hierarchy -Keep headings brief, organized, and in a logical order: - -- H1: Page title -- H2: Main headings -- H3: Subheadings -- H4: Sub-subheadings - -Try to stay within three or four heading levels. Detailed documents may use more, but pages with a simpler structure are easier to read. - -#### Punctuation in headings -Fleet headings do not use end punctuation unless the heading is a question: - -> Learn how to use osquery, nanoMDM, and Nudge to manage and monitor laptops and servers running Linux, Windows, ChromeOS, and macOS - -If the heading is a question, end the heading with a question mark. - - -### Sentence case -Fleet uses sentence case capitalization for all headings, subheadings, button text in the Fleet product, fleetdm.com, the documentation, the handbook, marketing material, direct emails, in Slack, and in every other conceivable situation. - -In sentence case, we write and capitalize words as if they were in sentences: - -> Ask questions about your servers, containers, and laptops running Linux, Windows, and macOS - -As we use sentence case, only the first word is capitalized. But, if a word would normally be capitalized in the sentence (e.g., a proper noun, an acronym, or a stylization) it should remain capitalized. - -- Proper nouns _("Nudge", "Skimbleshanks", "Kleenex")_ - - "Yeah, we use Nudge" - - "Introducing our friend Skimbleshanks" - - "Please, can I have a Kleenex?" -- Acronyms _("MDM", "REST", "API", "JSON")_ - - "MDM commands in Fleet are available over a REST API that returns JSON" -- Stylizations _("macOS", "osquery", "MySQL") - - "Although 'macOS' is a proper noun, macOS uses its own style guide from Apple, to which we adhere" - - "Zach is the co-creator of osquery" - - "Does it work with MySQL?" - -> Struggling with this? It takes some adjustment, and you need repetitions of seeing things written this way and correcting yourself. Many contributors have given the feedback that this opinionated solution is a huge relief once you build the habit of using sentence case capitalization, since it frees up mental capacity in every copywriting situation. You don't have to think as hard, nor choose between flouting and laboriously adhering to the (likely somewhat complex and out of date) styleguide. - -You can read about why we use sentence case in ["📖Company/Why this way?"](https://fleetdm.com/handbook/company/why-this-way#why-does-fleet-use-sentence-case). - -### Contractions -They’re great! Don’t be afraid to use them. They’ll help your writing sound more approachable. - -### Punctuation - -#### Ampersands (&) -Only use ampersands if they appear in a brand name, or if you’re quoting the title of an article from another source. Otherwise, write out “and.” - -#### Commas -When listing three or more things, use commas to separate the words. This is called a serial comma. - -**Do:** Fleet is for IT professionals, client platform engineers, and security practitioners. - -**Don’t:** Fleet is for IT professionals, client platform engineers and security practitioners. - -Aside from the serial comma, use commas, as usual, to break up your sentences. If you’re unsure whether you need a comma, saying the sentence aloud can give you a clue. If you pause or take a breath, that’s when you probably need a comma. - -#### Hyphens -**Do** use a hyphen to indicate a range: - -- Monday-Friday - -**Do** use a hyphen for compound modifiers. This is when 2 or more words function as one adjective. Compound modifiers precede the noun they modify: - -- We release Fleet on a three-week cadence. -- Osquery is an open-source agent. - -**Don’t** use a hyphen when modifying words follow the noun: - -- Fleet is released every three weeks. -- Osquery is open source. - -#### Colons -Colons introduce one or more elements that add detail to the idea before the colon. - -You can use a colon to introduce a list. - -- The Fleet product has 4 interfaces: Fleet UI, REST API, fleetctl CLI, and Fleet Desktop. - -You can also use a colon to introduce a phrase. - -- Introducing Sandbox: the fastest way to play with Fleet. - -Only capitalize the first word following a colon if it’s a proper noun (as in the example above). - -#### Exclamation points -They’re fun! But too many can undermine your credibility!!!1! Please use them sparingly. Take context into consideration. And only use one at a time. - -### Abbreviations and acronyms -If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it and specify the abbreviation in parentheses. Then use the short version for all other references. - -- A command-line interface (CLI) is a text-based user interface (UI) used to run programs, manage computer files, and interact with the computer. - -- The Fleet CLI is called fleetctl. - -If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out). - -### Numbers -Spell out a number when it begins a sentence. Otherwise, use the numeral. - -Sometimes numerals seem out of place. If an expression typically spells out the number, leave it as is: - -- First impression -- Third-party integration -- All-in-one platform - -Numbers over 3 digits get commas: - -- 999 -- 1,000 -- 150,000 - -#### Times -Use numerals and am or pm without a space in between: - -- 7am -- 7:30pm - -Use a hyphen between times to indicate a time period: - -- 7am–10:30pm - -We have users and Fleeties all over the world. Specify time zones when scheduling events or meetings. - -Abbreviate time zones within the continental United States as follows: - -- Eastern time: ET -- Central time: CT -- Mountain time: MT -- Pacific time: PT - -Spell out international time zones: - -- Central European Time -- Japan Standard Time - -### Emphasis - -#### Bold #### -Use bold text to emphasize words or phrases. Just don’t overdo it. Too much bold text may make it hard to see what’s really important. - -#### Italics #### - -Use italics when referencing UI elements (e.g., buttons and navigation labels): - -- On the settings page, go to *Organization Settings* and select *Fleet Desktop*. - -### Lists -Lists help readers scan content for essential information. They should be as concise and symmetrical as possible. - -If you find your list running long, or if each item contains several sentences, you may want to reconsider whether a list is the best approach. - -Use a numbered list if it follows a specific order or includes a set number of items. Otherwise, use bullet points. - -#### How to introduce a list -**Do** use a colon if you introduce a list with a complete sentence. - -**Don’t** use a colon if you start a list right after a heading. - -#### How to use end punctuation with list items -End punctuation refers to punctuation marks that are used to end sentences, such as periods, question marks, and exclamation points. - -**Do** use end punctuation if your list items are complete sentences: - -- Project confidence and be informative. -- Educate users about security threats positively. -- We never use fear as a marketing tactic. - -**Don’t** use end punctuation if your list items are sentence fragments, single words, or short phrases: - -- Policies -- Enterprise support -- Self-hosted agent auto-updates - -**Don’t** mix complete sentences with sentence fragments, single words, or short phrases. Consistent formatting makes lists easier to read. - -**Don’t** use commas or semicolons to end bullet points. - -#### How to capitalize list items -**Do** use a capital letter at the beginning of every bullet point. The only exceptions are words that follow specific style guides (e.g., macOS). - -## Web elements - -### SQL statements - -When adding SQL statements, all SQL reserved words should be uppercase, and all identifiers (such as tables and columns) should be lowercase. Here’s an example: - -`SELECT days, hours, total_seconds FROM uptime;` - -### Markdown -Markdown is a simple formatting syntax used to write content on the web. In order to publish content like articles, docs, or handbook entries, you must format your content in Markdown. Refer to our [Markdown guide](https://fleetdm.com/handbook/marketing/markdown-guide) for help with formatting headings, lists, tables, and more. - -## 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. - -## Writing documentation -You don’t have to be a “writer” to write documentation. Nobody knows Fleet better than the people who are building our product. That puts developers in the perfect position to show users what Fleet can do. - -This guide will help you write docs that help users achieve their goals with Fleet. - -### Remember the reader -People come from different backgrounds. New users may not know terms that are common knowledge for seasoned developers. Since Fleet has users all over the world, English may not be their first language. Your writing must be easy for any user to understand. - -- **Think of every user.** Define technical terms in the doc or include a link. -- **Strive for simplicity.** Avoid complex sentences and long paragraphs. -- **Be approachable.** Write like you’re meeting a new member of your team. - -### Answer the question -It’s what we’re all about at Fleet. People read docs in order to accomplish their goals. Those goals can vary from learning about Fleet for the first time to looking for troubleshooting tips. Make sure your doc meets the specific need of the user at that moment. - -- **Understand the question.** Be clear about the topic you’re discussing. -- **Narrow your focus.** Avoid explanations that distract from the main topic. -- **No more, no less.** Use just enough information to give an accurate answer. - -### Follow a framework -Starting with a blank page can be scary. That’s why it helps to have a framework for your writing. Follow these four steps to write your docs: introduction, explanation, reference, and troubleshooting. - -#### Introduction -Give an overview of the topic. You don’t need to mention everything at the beginning. Briefly establish the question you’re addressing. People want to get to the answer A.S.A.P. - -#### Explanation -You’ve let users know why they’re reading your doc. It’s time to make sure they understand the topic. This will be most of your documentation. Don’t shy away from details. - -#### Reference -Support your explanation with relevant references. This shows users how to put your explanation into practice. Such material will keep users coming back. - -#### Troubleshooting -Nothing is perfect. Your readers understand this. Users will appreciate it if you identify common problems — and provide solutions — before they encounter these issues later. - -### Document every change -Any change to Fleet’s code should be documented, from adding patches to building features. This allows users and Fleeties to stay up to date with improvements to our product. - -You don’t need to wait until a change has been made to write a new doc. Starting with documentation can help you discover ways to make Fleet even better. - -Writing about how to use a new feature puts you in the shoes of the user. If something seems complicated, you have the opportunity to improve it — before committing a line of code. - - - - diff --git a/handbook/marketing/docs-handbook.md b/handbook/marketing/docs-handbook.md deleted file mode 100644 index be2e64310..000000000 --- a/handbook/marketing/docs-handbook.md +++ /dev/null @@ -1,133 +0,0 @@ -# Docs handbook - -This page details processes related to maintaining and updating the ([Fleet docs](https://fleetdm.com/docs)). - -## Responsibilities - -The [website group](https://fleetdm.com/handbook/company/product-groups#website-group) is responsible for maintaining the Fleet documentation. - -## Documentation DRIs - -TODO: Document. - -## Intake - -When someone asks a question in a public channel, it's pretty safe to assume that they aren't the only person looking for an answer to the same question. To make our docs as helpful as possible, the Community team gathers these questions and uses them to make a weekly documentation update. - -Our goal is to answer every question with a link to the docs and/or result in a documentation update. - -> **Remember**, when submitting any pull request that changes Markdown files in the docs, request an editor review from Kathy Satterlee, who will escalate to the [on-call engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) as needed. - -## Tracking - -When responding to a question or issue in the [#fleet](https://osquery.slack.com/join/shared_invite/zt-h29zm0gk-s2DBtGUTW4CFel0f0IjTEw#/) channel of the osquery Slack workspace, push the thread to Zapier using the `TODO: Update docs` Zap. This will add information about the thread to the [Slack Questions Spreadsheet](https://docs.google.com/spreadsheets/d/15AgmjlnV4oRW5m94N5q7DjeBBix8MANV9XLWRktMDGE/edit#gid=336721544). In the `Notes` field, you can include any information that you think will be helpful when making weekly doc updates. That may be something like - -- proposed change to the documentation. -- documentation link that was sent as a response. -- link to associated thread in [#help-oncall](https://fleetdm.slack.com/archives/C024DGVCABZ). - -## Content reviews - -When creating a pull request for Markdown changes in the docs, request a review from Kathy Satterlee, who will do an editor pass, and then hand over the review to the [oncall engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) if necessary. - -## Markdown - -The Fleet docs are written in Markdown. Using Markdown lets us keep our documentation consistently formatted and viewable directly from the Fleet GitHub repo. - -See the [Markdown guide](./markdown-guide) for help formatting Fleet-flavored Markdown. - -## Links - -You can link documentation pages to each other using relative paths. For example, in `docs/Using-Fleet/Fleet-UI.md`, you can link to `docs/Using-Fleet/Permissions.md` by writing `[permissions](./Permissions.md)`. This will automatically be transformed into the appropriate URL for `fleetdm.com/docs`. - -However, the `fleetdm.com/docs` compilation process does not account for relative links to directories **outside** of `/docs`. -This is why it’s essential to follow the file path exactly when adding a link to Fleet docs. -When directly linking to a specific section, always format the spaces within a section name to use a hyphen instead of an underscore. For example, when linking to the `osquery_result_log_plugin` section of the configuration reference docs, use a relative link like the following: `./Configuration.md#osquery-result-log-plugin`. - -### Linking to a location on GitHub - -When adding a link to a location on GitHub outside of `/docs`, be sure to use the canonical form of the URL. - -Navigate to the file's location on GitHub, and press "y" to transform the URL into its canonical form. - -### Fixing a broken link - -For instances when a broken link is discovered on fleetdm.com, always check if the link is a relative link to a directory outside of `/docs`. - -An example of a link that lives outside of `/docs` is: - -``` -../../tools/app/prometheus -``` - -If the link lives outside `/docs`, head to the file's location on GitHub (in this case, [https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)](https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)), and press "y" to transform the URL into its canonical form (a version of the link that will always point to the same version of the file) ([https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml](https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml)). Replace the relative link with this link in the Markdown file. - -> Note that the instructions above also apply to adding links in the Fleet handbook. - -## Meta tags - -### Page order - -The order we display documentation pages on fleetdm.com is determined by `pageOrderInSection` meta tags. These pages are sorted in their respective sections in **ascending** order by the `pageOrderInSection` value. Every Markdown file (except readme and faq pages) in the `docs/` folder must have a meta tag with a positive 'pageOrderInSection' value. - -We leave large gaps between values to make future changes easier. For example, the first page in the "Using Fleet" section of the docs has a `pageOrderInSection` value of 100, and the next page has a value of 200. The significant difference between values allows us to add, remove and reorder pages without changing the value of multiple pages at a time. - -When adding or reordering a page, try to leave as much room between values as possible. If you were adding a new page that would go between the two pages from the example above, you would add `` to the page. - -### Page description - -TODO: Document. - -## Images - -Try to keep images in the docs at a minimum. Images can be a quick way to help users understand a concept or direct them towards a specific user interface(UI) element. Still, too many can make the documentation feel cluttered and more difficult to maintain. - -When adding images to the Fleet documentation, follow these guidelines: - -- UI screenshots should be a 4:3 aspect ratio (1280x960). This is an optimal size for the container width of the docs and ensures that content in screenshots is as clear as possible to view in the docs (and especially on mobile devices). -- You can set up a custom preset in the Google Chrome device toolbar (in Developer Tools) to quickly adjust your browser to the correct size for taking a screenshot. -- Keep the images as simple as possible to maintain. Screenshots can get out of date quickly as UIs change. -- Exclude unnecessary images. Images should be used to help emphasize information in the docs, not replace it. -- Minimize images per doc page. For doc maintainers and users, more than one or two per page can get overwhelming. -- The goal is for the docs to look good on every form factor, from 320px window width all the way up to infinity. Full window screenshots and images with too much padding on the sides will be less than the width of the user's screen. When adding a large image, make sure it is easily readable at all widths. - -Images can be added to the docs using the Markdown image link format, e.g., `![Schedule Query Sidebar](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/add-new-host-modal.png)` -The images used in the docs live in `docs/images/`. Note that you must provide the URL of the image in the Fleet GitHub repo for it to display properly on both GitHub and the Fleet website. - -> Note that the instructions above also apply to adding images in the Fleet handbook. - -## Mermaid diagrams - -The Fleet Docs support diagrams that are written in mermaid.js syntax. Take a look at the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/README) to learn about the syntax language and what types of diagrams you can display. - -To add a mermaid diagram to the docs, you need to add a code block and specify that it is written in the mermaid language by adding `mermaid` to the opening backticks (i.e., ` ```mermaid`). - -For example, the following code block is a mermaid diagram that has **not** been specified as a mermaid code block: - -``` -graph TD; - A-->D - B-->D - C-->D - D-->E -``` - -Once we specify the `mermaid` as the language in the code block, it will render as a mermaid diagram on fleetdm.com and GitHub. - -```mermaid -graph TD; - A-->D - B-->D - C-->D - D-->E -``` - -If the mermaid syntax is incorrect, the diagram will be replaced with an image displaying an error, as shown in the following example where the code block was written with **intentional** syntax errors: - -```mermaid -graph TD; - A--D -``` - - - diff --git a/handbook/marketing/editor-guide.md b/handbook/marketing/editor-guide.md deleted file mode 100644 index 072ea5661..000000000 --- a/handbook/marketing/editor-guide.md +++ /dev/null @@ -1,70 +0,0 @@ -# Editor guide - -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 make edits with GitHub - -Our handbook and docs pages are written in Markdown and are editable from our website (via GitHub). Follow the instructions below to propose an edit to the handbook or docs. -1. Click the "Edit page" button from the relevant handbook or docs page on [fleetdm.com](https://www.fleetdm.com) (this will take you to the GitHub editor). -2. Make your suggested edits in the GitHub editor. -3. From the Propose changes dialog, at the bottom of the page, give your proposed edit a title and optional description (these help page maintainers quickly understand the proposed changes). -4. Hit Propose change which will open a new pull request (PR). -5. Request a review from the page maintainer, and finally, press “Create pull request.” -6. GitHub will run a series of automated checks and notify the reviewer. At this point, you are done and can safely close the browser page at any time. - -> Keep PR titles short and clear. E.g., "Edit to handbook Product group" -> -> Check the “Files changed” section on the Open a pull request page to double-check your proposed changes. - -#### How to edit recently merged pull requests for the handbook - -We approach editing retrospectively for pull requests (PRs) to handbook pages. Remember our goal above about moving quickly and reducing time to value for our contributors? We avoid the editor becoming a bottleneck for merging quickly by editing for typos and grammatical errors after-the-fact. Here's how to do it: - -> **Note:** Contributors are not required to request reviews from editors for handbook changes. - -1. Check that the previous day's edits are formatted correctly on the website (more on this in the note below.) -2. Use the [Handbook history](https://github.com/fleetdm/fleet/commits/main/handbook) feed in GitHub to see a list of changes made to the handbook. -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](https://fleetdm.com/handbook/brand#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](https://www.loom.com/share/95d4525a7aae482b9f9a9470d446ce9c) 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 Markdown pull requests for the docs - -- When someone creates a pull request for a doc that affects Markdown files, they’ll need to request a review from the editor. -- If no edits are needed, the editor will merge the PR. -- If an edit changes the meaning, or if unsure, the editor should request a review from the [on-call engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) and remove themselves as a reviewer. - -#### How to edit articles, release posts, and press releases - -Editing articles, release posts, and press releases usually comes in three flavors: a Google Docs draft, a new pull request, or an edit to an existing article. - -* For unpublished articles, please read the review process in [How to submit and publish an article](https://fleetdm.com/handbook/marketing/how-to-submit-and-publish-an-article#review-process). - -* To edit an existing article, see [How to make edits with GitHub](#how-to-make-edits-with-github). - -#### 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. - -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-marketing Slack channel and tag the Brand team 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 Marketing team to include and re-post. - - - - diff --git a/handbook/marketing/markdown-guide.md b/handbook/marketing/markdown-guide.md deleted file mode 100644 index 6fad34b07..000000000 --- a/handbook/marketing/markdown-guide.md +++ /dev/null @@ -1,248 +0,0 @@ -# Markdown guide - -The Markdown files in the [/docs](https://fleetdm.com/docs), [/handbook](https://fleetdm.com/handbook), and [/articles](https://fleetdm.com/articles) folders in the [Fleet repo](https://github.com/fleetdm/fleet) are converted to HTML for the Fleet website. - -This guide is here to help you format consistent Fleet-flavored Markdown. - -## Headings - -Try to stay within three or four heading levels. Complicated documents may use more, but pages with a simpler structure are easier to read. - -| Markdown | Rendered heading | -|:--------------------|:-----------------------------| -| `# Heading 1` |

Heading 1

| -| `## Heading 2` |

Heading 2

| -| `### Heading 3` |

Heading 3

| -| `#### Heading 4` |

Heading 4

| - -## Emphasis - -| Markdown | Rendered text | -|:--------------------|:-----------------------------| -| `**Bold**` | Bold | -| `*Italic*` | Italic | -| `***Bold italic***` | Bold italic | -| `~~Strikethrough~~` | Strikethrough | - -## Line breaks and new lines - -Any time you need to add a line break in Markdown, you should add a new line. It is vital to make sure paragraphs are separated by new lines. Otherwise, they will render as the same HTML element. - -For example, if you were adding this section: - -``` -line one -line two -``` - -The Markdown would render on the Fleet website as - -line one -line two - -To make sure formatting is consistent across GitHub and the Fleet website, you need to add a new line anywhere you want a line break. For example, if we separate the lines with a new line: - -``` -line one - -line two -``` - -The Markdown will render correctly as - -line one - -line two - -## Lists - -### Ordered lists - -| Markdown | Rendered list | -|:-------------|:-----------------------------| -| 
1. Line one
2. Line two  
3. Line three
4. Line four
| 1. Line one
2. Line two
3. Line three
4. Line four | -| 
1. Line one
1. Indent one
2. Line two
3. Line three
1. Indent one
2. Indent two
4. Line four
| 1. Line one
 1. Indent one
2. Line two
3. Line three
 1. Indent one
 2. Indent two
4. Line four | - -Content nested within an ordered list needs to be indented. If the list is not formatted correctly, the number will reset on each list item, as shown in the example below. - -**Markdown:** - -``` -1. Item one - -Paragraph about item one - -2. Item two -``` - -**Rendered output:** - -1. Item one - -Paragraph about item one - -2. Item two - -To make sure that ordered lists increment correctly, you can indent the content nested within the list. For example, the same ordered list with indentation: - -**Markdown:** - -``` -1. Item one - - Paragraph about item one - -2. Item two -``` - -**Rendered output:** - -1. Item one - - Paragraph about item one - -2. Item two - -### Unordered lists - -| Markdown | Rendered list | -|:-------------|:-----------------------------| -| 
- Line one
- Line two  
- Line three
- Line four
| - Line one
- Line two
- Line three
- Line four | -| 
- Line one
 - Indent one
- Line two
- Line three
 - Indent one
 - Indent two
- Line four
| - Line one
 - Indent one
- Line two
- Line three
 - Indent one
 - Indent two
- Line four | - -## Links - -The Fleet website currently supports the following Markdown link types. - -### Inline link - -It's a classic. - -#### Example - -`[This is an inline link](https://domain.com/example.md)` - -#### Rendered output - -[This is an inline link](https://domain.com/example.md) - -### Link with a tooltip - -Adding a tooltip to your link is a great way to provide additional information. - -#### Example - -`[This is link with a tooltip](https://domain.com/example.md "You're awesome!")` - -#### Rendered output - -[This is link with a tooltip](https://domain.com/example.md "You're awesome!") - -### URLs - -Add angle brackets "< >" around a URL to turn it into a link. - -#### Example - -`` - -#### Rendered output - - - -### Emails - -To create a mailto link... oh wait, I'm not going to tell you. - -> **Important**: To avoid spam, we **NEVER** use mailto links. - -## Tables - -To create a table, start with the header by separating rows with pipes (" | "). -Use dashes (at least 3) to separate the header, and add colons to align the text in the table columns. - -#### Example - -``` -| Category one | Category two | Category three | -|:---|---:|:---:| -| Left alignment | Right alignment | Center Alignment | -``` - -#### Rendered output - -| Category one | Category two | Category three | -|:---|---:|:---:| -| Left alignment | Right alignment | Center Alignment | - -## Blockquotes - -To add a tip blockquote, start a line with ">" and end the blockquote with a blank newline. - -### Tip blockquotes - -Tip blockquotes are the default blockquote style in our Markdown content. - -#### Example - -``` -> This is a tip blockquote. -This line is rendered inside of the tip blockquote. - -This line is rendered outside of the tip blockquote. -``` - -#### Rendered output - -> This is a tip blockquote. -This line is rendered inside of the tip blockquote. - -This line is rendered outside of the tip blockquote. - -### Quote blockquotes - -To add a quote blockquote, add a `
` HTML element with `purpose="quote"`. - -#### Example - -``` -
-This is a quote blockquote. - -Lines seperated by a blank newline will be rendered on a different line in the blockquote. -
-``` - -#### Rendered output - -
-This is a quote blockquote. - -Lines seperated by a blank newline will be rendered on a different line in the blockquote. -
- -### Large quote blockquote - -You can add a large quote blockquote by adding a `
` HTML element with `purpose="large-quote"`. - -#### Example - -``` -
-This is a large blockquote. - -You can use a large quote blockquote to reduce the font size and line height of the rendered text. -
-``` - -#### Rendered output - -
-This is a large blockquote. - -You can use a large quote blockquote to reduce the font size and line height of the rendered text. -
- - - - diff --git a/handbook/marketing/website-handbook.md b/handbook/marketing/website-handbook.md deleted file mode 100644 index b661e4da0..000000000 --- a/handbook/marketing/website-handbook.md +++ /dev/null @@ -1,355 +0,0 @@ -# Website handbook - -This page details processes related to maintaining and updating the Fleet website ([fleetdm.com](https://fleetdm.com)). - -Website-related topics that are NOT included on this page: -- [Publishing an article](https://fleetdm.com/handbook/marketing/how-to-submit-and-publish-an-article) - -## Responsibilities - -The [website group](https://fleetdm.com/handbook/company/product-groups#website-group) is responsible for production and maintenance of the Fleet website. - -## Website roadmap - -View planned changes to the website on the website group's [sprint board](https://app.zenhub.com/workspaces/g-website-6451748b4eb15200131d4bab/board?sprints=none). - -## Requesting changes - -See Marketing [intake](https://fleetdm.com/handbook/marketing#intake) for more information on how the website team prioritizes new requests. Bugs are always prioritized first. - -## Wireframes - -Before committing anything to code, we create wireframes (referred to as ["drafting"](https://fleetdm.com/handbook/company/development-groups#making-changes)) to illustrate all changes that affect the layout and structure of the user interface, design, or APIs of fleetdm.com. - -See [Why do we use a wireframe first approach](https://fleetdm.com/handbook/company/why-this-way#why-do-we-use-a-wireframe-first-approach) for more information. - -## Design reviews - -We hold regular design review sessions to evaluate, revise, and approve wireframes before moving into production. - -Design review sessions are hosted by [Mike Thomas](https://calendar.google.com/calendar/u/0?cid=bXRob21hc0BmbGVldGRtLmNvbQ) and typically take place daily, late afternoon (CST). Anyone is welcome to join. - -## Estimation sessions - -We use estimation sessions to estimate the effort required to complete a prioritized task. - -Through these sessions, we can: - -- Confirm that wireframes are complete before moving to production. -- Consider all edge cases and requirements that may have been with during wireframing. -- Avoid having the engineer make choices for “unknowns” during production. -- More accurately plan and prioritize upcoming tasks. - -### Story points - -Story points represent the effort required to complete a task. After accessing wireframes, we typically play planning poker, a gamified estimation technique, to determine the necessary story point value. - -We use the following story points to estimate website tasks: - -| Story point | Time | -|:---|:---| -| 1 | 1 to 2 hours | -| 2 | 2 to 4 hours | -| 3 | 1 day | -| 5 | 1 to 2 days | -| 8 | Up to a week | -| 13 | 1 to 2 weeks | - -## Quality - -Quality assurance (QA) checks must be completed before changes to the website can be merged. Read on to learn about the quality assurance process for the website. - -> **Important:** A PR to the website should not be merged until the quality assurance process has been successfully completed. - -### Manual QA - -The product manager of the website group is responsible for making sure that manual QA steps have been added to requests. - -### Writing QA steps - -QA steps are step-by-step instructions used to confirm that changed to the website function as expected. They should be simple and clear enough for anybody to follow. Example steps are included in [the “Website request” issue template](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=%23g-website&template=website-request.md&title=Request%3A+__________________________). - -### Actioning QA steps - -[View the website locally](#test-changes-to-the-website) and follow the QA steps in the request ticket to test changes. - -QA steps should be actioned when a request has been moved into the “Review/QA” column of the website product board. PRs to the website should not be merged until QA has been completed. - -A successful QA check can be indicated by leaving a comment in the conversation thread of the PR. - -### Additional QA - -In addition to the steps above. All website changes must be thoroughly checked at all breakpoints and a [browser compatibility](#browser-compatibility) test should be carried out on [supported browsers](https://fleetdm.com/docs/using-fleet/supported-browsers) before website changes can go live. - -## Testing changes - -When making changes to the Fleet website, you can test your changes by running the website locally. To do this, you'll need the following: - -- A local copy of the [Fleet repo](https://github.com/fleetdm/fleet). -- [Node.js](https://nodejs.org/en/download/) -- (Optional) [Sails.js](https://sailsjs.com/) installed globally on your machine (`npm install sails -g`) - -Once you have the above follow these steps: - -1. Open your terminal program, and navigate to the `website/` folder of your local copy of the Fleet repo. - - > Note: If this is your first time running this script, you will need to run `npm install` inside of the website/ folder to install the website's dependencies. - - -2. Run the `build-static-content` script to generate HTML pages from our Markdown and YAML content. - - **With Node**, you will need to use `node ./node_modules/sails/bin/sails run build-static-content` to execute the script. - - **With Sails.js installed globally** you can use `sails run build-static-content` to execute the script. - - > You can use the `--skipGithubRequests` flag to skip requests made to GitHub if you get rate-limited by GitHub’s API while running this script. - > - > e.g., `node ./node_modules/sails/bin/sails run build-static-content --skipGithubRequests` - -3. Once the script is complete, start the website server. From the `website/` folder: - - **With Node.js:** start the server by running `node ./node_modules/sails/bin/sails lift` - - **With Sails.js installed globally:** start the server by running `sails lift`. -4. When the server has started, the Fleet website will be availible at [http://localhost:2024](http://localhost:2024) - - > **Note:** Some features, such as Fleet Sandbox, Self-service license dispenser, and account creation are not availible when running the website locally. If you need help testing features on a local copy, reach out to `@eashaw` in the [#g-website](https://fleetdm.slack.com/archives/C058S8PFSK0) channel on Slack.. - -## Merging changes -When merging a PR to the master branch of the [Fleet repo](https://github.com/fleetdm/fleet), remember that whatever you merge gets deployed live immediately. Ensure that the appropriate quality checks have been completed before merging. [Learn about the website QA process](#quality). - -When merging changes to the [docs](https://fleetdm.com/docs), [handbook](https://fleetdm.com/handbook), and articles, make sure that the PR’s changes do not contain inappropriate content (goes without saying) or confidential information, and that the content represents our [brand](#brand) accordingly. When in doubt reach out to the product manager of the [website group](https://fleetdm.com/handbook/company/product-groups#website-group) in the [#g-website](https://fleetdm.slack.com/archives/C058S8PFSK0) channel on Slack. - -### 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](https://heroku.com) 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. - -## 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). - -- 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 them for fixing. -- If in doubt about anything regarding design or layout, please reach out to the Design team. - -## Error handling - -### 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. - -### Incident post-mortems - -When conducting an incident post-mortem, answer the following three questions: - -1. Impact: What impact did this error have? How many humans experienced this error, if any, and who were they? -2. Root Cause: Why did this error happen? -3. Side effects: did this error have any side effects? e.g., did it corrupt any data? Did code that was supposed to run afterward and “finish something up” not run, and did it leave anything in the database or other systems in a broken state requiring repair? This typically involves checking the line in the source code that threw the error. - -## Vulnerability monitoring - -Every week, we run `npm audit --only=prod` to check for vulnerabilities on the production dependencies of fleetdm.com. Once we have a solution to configure GitHub's Dependabot to ignore devDependencies, this manual process can be replaced with Dependabot. - -## Experimentation - -In order for marketing to iterate rapidly we have created a process of experimentation. This will allow a small group of marketers to draft, review and publish a page or a flyer or an experiment without getting a series of approvals. Experiments should be short-lived, temporary things intended for a small audience. When an experiment succeeds it should immediately be turned into a part of Fleet'd rituals and then go through the proper wireframe-first approach. - -Website experiments and landing pages should live behind `/imagine` url. Which is hidden from the sitemap and intended to be linked to from ads and marketing campaigns. Design experiments (flyers, swag, etc.) should be limited to small audiences (less than 500 people) to avoid damaging the brand or confusing our customers. In general, experiments that are of a design nature should be targeted at prospects and random users, never targeted at our customers. - -Some examples of experiments that would qualify to get a rapid approach: -- A flyer for a meetup "Free shirt to the person who can solve this riddle!" -- A landing page for a movie screening presented by Fleet -- A landing page for a private event -- A landing page for an ad campaign that is running for 4 weeks. -- An A/B test on product positioning -- A giveaway page for a conference -- Table-top signage for a conference booth or meetup - -### Landing pages - -The Fleet website has a built-in landing page generator that can be used to quickly create a new page that lives under the /imagine/ url. - -To generate a new page, you'll need: - -- A local copy of the [Fleet repo](https://github.com/fleetdm/fleet). -- [Node.js](https://nodejs.org/en/download/) -- (Optional) [Sails.js](https://sailsjs.com/) installed globally on your machine (`npm install sails -g`) - -1. Open your terminal program, and navigate to the `website/` folder of your local copy of the Fleet repo. - - > Note: If this is your first time running the website locally, you will need to run `npm install` inside of the website/ folder to install the website's dependencies. - -2. Call the `landing-page` generator by running `node ./node_modules/sails/bin/sails generate landing-page [page-name]`, replacing `[page-name]` with the kebab-cased name (words seperated by dashes `-`) of your page. - -3. After the files have been generated, you'll need to manually update the website's routes. To do this, copy and paste the generated route for the new page to the "Imagine" section of `website/config/routes.js`. - -4. Next you need to update the stylesheets so that the page can inherit the correct styles. To do this, copy and paste the generated import statement to the "Imagine" section of `website/assets/styles/importer.less`. - -5. Start the website by running `node ./node_modules/sails/bin/sails lift` (or `sails lift` if you have Sails installed globally). The new landing page will be availible at `http://localhost:1337/imagine/{page-name}`. - -6. Replace the lorum ipsum and placeholder images on the generated page with the page's real content, and add a meta description and title by changing the `pageTitleForMeta` and `pageDescriptionForMeta in the page's `locals` in `website/config/routes.js`. - - -## 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. - -## Website services - -### Cloudflare - -We use Cloudflare to manage the DNS records of fleetdm.com and our other domains. Cloudflare offers a free, user-friendly, and cloud-agnostic interface that allows authorized team members to manage all our domains easily. -If you need access to Fleet's Cloudflare account, please ask the [DRI](https://fleetdm.com/handbook/company/why-this-way#why-direct-responsibility) Zach Wasserman in Slack for an invitation. - - -To make DNS changes in Cloudflare: -1. Log into your Cloudflare account and select the "Fleet" account. -2. Select the domain you want to change and go to the DNS panel on that domain's dashboard. -3. To add a record, click the "Add record" button, select the record's type, fill in the required values, and click "Save". If you're making changes to an existing record, you only need to click on the record, update the record's values, and save your changes. - -### Heroku - -TODO: Document. - -### Algolia - -TODO: Document. - -## Docs - -This page details processes related to maintaining and updating the ([Fleet docs](https://fleetdm.com/docs)). - -When someone asks a question in a public channel, it's safe to assume they aren't the only person looking for an answer. - -To make our docs as helpful as possible, the Community team gathers these questions and uses them to make a weekly documentation update. - -Fleet's goal is to answer every question with a link to the docs and/or result in a documentation update. - -### Documentation DRIs - -TODO: Document. - -### Tracking - -When responding to a question or issue in the [#fleet](https://osquery.slack.com/join/shared_invite/zt-h29zm0gk-s2DBtGUTW4CFel0f0IjTEw#/) channel of the osquery Slack workspace, push the thread to Zapier using the `TODO: Update docs` Zap. This will add information about the thread to the [Slack Questions Spreadsheet](https://docs.google.com/spreadsheets/d/15AgmjlnV4oRW5m94N5q7DjeBBix8MANV9XLWRktMDGE/edit#gid=336721544). In the `Notes` field, you can include any information that you think will be helpful when making weekly doc updates. That may be something like - -- proposed change to the documentation. -- documentation link that was sent as a response. -- link to associated thread in [#help-oncall](https://fleetdm.slack.com/archives/C024DGVCABZ). -- **Note:** When submitting any pull request that changes Markdown files in the docs, request an editor review from Kathy Satterlee, who will escalate to the [on-call engineer](https://fleetdm.com/handbook/engineering#oncall-rotation) as needed. - - -### Markdown - -The Fleet docs are written in Markdown. Using Markdown lets us keep our documentation consistently formatted and viewable directly from the Fleet GitHub repo. - -See the [Markdown guide](https://fleetdm.com/handbook/company/communications#writing-in-fleet-flavored-markdown) for help formatting Fleet-flavored Markdown. - - - - -#### Linking to a location on GitHub - -When adding a link to a location on GitHub outside of `/docs`, be sure to use the canonical form of the URL. - -Navigate to the file's location on GitHub, and press "y" to transform the URL into its canonical form. - -### Fixing a broken link - -For instances when a broken link is discovered on fleetdm.com, always check if the link is a relative link to a directory outside of `/docs`. - -An example of a link that lives outside of `/docs` is: - -``` -../../tools/app/prometheus -``` - -If the link lives outside `/docs`, head to the file's location on GitHub (in this case, [https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)](https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)), and press "y" to transform the URL into its canonical form (a version of the link that will always point to the same version of the file) ([https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml](https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml)). Replace the relative link with this link in the Markdown file. - -> Note that the instructions above also apply to adding links in the Fleet handbook. - -### Meta tags - -#### Page order - -The order we display documentation pages on fleetdm.com is determined by `pageOrderInSection` meta tags. These pages are sorted in their respective sections in **ascending** order by the `pageOrderInSection` value. Every Markdown file (except readme and faq pages) in the `docs/` folder must have a meta tag with a positive 'pageOrderInSection' value. - -We leave large gaps between values to make future changes easier. For example, the first page in the "Using Fleet" section of the docs has a `pageOrderInSection` value of 100, and the next page has a value of 200. The significant difference between values allows us to add, remove and reorder pages without changing the value of multiple pages at a time. - -When adding or reordering a page, try to leave as much room between values as possible. If you were adding a new page that would go between the two pages from the example above, you would add `` to the page. - -#### Page description - -TODO: Document. - -### Images - -Try to keep images in the docs at a minimum. Images can be a quick way to help users understand a concept or direct them towards a specific user interface(UI) element. Still, too many can make the documentation feel cluttered and more difficult to maintain. - -When adding images to the Fleet documentation, follow these guidelines: - -- UI screenshots should be a 4:3 aspect ratio (1280x960). This is an optimal size for the container width of the docs and ensures that content in screenshots is as clear as possible to view in the docs (and especially on mobile devices). -- You can set up a custom preset in the Google Chrome device toolbar (in Developer Tools) to quickly adjust your browser to the correct size for taking a screenshot. -- Keep the images as simple as possible to maintain. Screenshots can get out of date quickly as UIs change. -- Exclude unnecessary images. Images should be used to help emphasize information in the docs, not replace it. -- Minimize images per doc page. For doc maintainers and users, more than one or two per page can get overwhelming. -- The goal is for the docs to look good on every form factor, from 320px window width all the way up to infinity. Full window screenshots and images with too much padding on the sides will be less than the width of the user's screen. When adding a large image, make sure it is easily readable at all widths. - -Images can be added to the docs using the Markdown image link format, e.g., `![Schedule Query Sidebar](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/add-new-host-modal.png)` -The images used in the docs live in `docs/images/`. Note that you must provide the URL of the image in the Fleet GitHub repo for it to display properly on both GitHub and the Fleet website. - -> Note that the instructions above also apply to adding images in the Fleet handbook. - -### Mermaid diagrams - -The Fleet Docs support diagrams that are written in mermaid.js syntax. Take a look at the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/README) to learn about the syntax language and what types of diagrams you can display. - -To add a mermaid diagram to the docs, you need to add a code block and specify that it is written in the mermaid language by adding `mermaid` to the opening backticks (i.e., ` ```mermaid`). - -For example, the following code block is a mermaid diagram that has **not** been specified as a mermaid code block: - -``` -graph TD; - A-->D - B-->D - C-->D - D-->E -``` - -Once we specify the `mermaid` as the language in the code block, it will render as a mermaid diagram on fleetdm.com and GitHub. - -```mermaid -graph TD; - A-->D - B-->D - C-->D - D-->E -``` - -If the mermaid syntax is incorrect, the diagram will be replaced with an image displaying an error, as shown in the following example where the code block was written with **intentional** syntax errors: - -```mermaid -graph TD; - A--D -``` - - -## Rituals -| Ritual | Frequency | Description | DRI | -|:-----------------------------|:-------------------------|:----------------------------------------------------|-------------------| -| Generate latest schema | once every 3 weeks | After each sprint, generate the latest tables json file to incorporate any new schema documentation. | Eric Shaw | - - - - diff --git a/website/config/routes.js b/website/config/routes.js index c8bcf5c7f..f7aa66580 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -392,8 +392,14 @@ module.exports.routes = { 'GET /handbook/digital-experience': '/handbook/marketing#digital-experience', 'GET /handbook/digital-experience/article-formatting-guide': '/handbook/marketing/article-formatting-guide', 'GET /handbook/digital-experience/commonly-used-terms': '/handbook/marketing/commonly-used-terms', + 'GET /handbook/marketing/commonly-used-terms': '/handbook/company/communications#commonly-used-terms', 'GET /handbook/digital-experience/how-to-submit-and-publish-an-article': '/handbook/marketing/how-to-submit-and-publish-an-article', 'GET /handbook/digital-experience/markdown-guide': '/handbook/marketing/markdown-guide', + 'GET /handbook/marketing/markdown-guide': '/handbook/company/communications#writing-in-fleet-flavored-markdown', + 'GET /handbook/marketing/content-style-guide': '/handbook/company/communications#writing', + 'GET /handbook/marketing/editor-guide/': '/handbook/company/communications#github', + 'GET /handbook/marketing/docs-handbook/': '/handbook/company/communications', + 'GET /handbook/marketing/website-handbook/': '/handbook/company/communications', 'GET /handbook/quality': '/handbook/engineering#quality', 'GET /device-management/fleet-user-stories-f100': '/success-stories/fleet-user-stories-wayfair', 'GET /device-management/fleet-user-stories-schrodinger': '/success-stories/fleet-user-stories-wayfair',