Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-05-24 09:28:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 52

Marketing and brand handbook house keeping. (#12281)

Browse source 
I got [nerd sniped](https://en.wikipedia.org/wiki/Nerd_sniping) while
adding the QA process for the website and did some long overdue
housekeeping of the brand section of the handbook. There's still more to
do, but this is a good start.

## Changes

- Updated the `maintainedby` meta tag on `commonly-used-terms.md`
- Added a line break that I spotted on `content-style-guide.md`
- Moved the docs handbook content to its own page and linked to it from
the marketing page of the handbook to reduce the excessive scroll.
- Consolidated the Markdown instructions from the docs handbook section
into `markdown-guide.md` and linked to it from the relevant section of
the docs handbook page.
- Moved the website handbook content to its own handbook page and linked
to it from the marketing page of the handbook to reduce the excessive
scroll.
- Added quality assurance process to the website handbook page.
- Re-ordered the brand section of the handbook to show brand resources
and content style guide first.

## QA

- [x] Manual QA for all new/changed functionality
This commit is contained in:
Mike Thomas 2023-06-12 18:18:51 +09:00 committed by GitHub
parent 3628dd2bf0
commit 1b10de518a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 546 additions and 484 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

516
handbook/marketing/README.md
View file

@ -282,6 +282,32 @@ At this time, double-check that information within Salesforce and Typeform is ac
## Brand
### Brand resources
To download official Fleet logos, product screenshots, and wallpapers, head over to our [brand resources](https://fleetdm.com/logos) page.
See [About Fleet Device Management](#about-fleet-device-management) for ready-to-go descriptions of Fleet and for the press-release boilerplate.
#### Figma
We use Figma for most of our design work. This includes the Fleet product, our website, and our marketing collateral.
##### Which file should I use?
**Fleet product** All product design work is done in the [Fleet EE (scratchpad)](https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=9209%3A302838) Figma doc. Check out the [README](https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=2750%3A67203) for how to use this doc.
**Fleet website.** All website design work is done in the [fleetdm.com (current, dev-ready)](https://www.figma.com/file/yLP0vJ8Ms4GbCoofLwptwS/%E2%9C%85-fleetdm.com-(current%2C-dev-ready)?node-id=794%3A373) Figma file.
**Design system.** Shared logos, typography styles, and UI components can be found in [Design system](https://www.figma.com/files/project/15701210).
> The Figma docs in Design System contain the master components that are referenced throughout all other Figma files. Use caution when modifying these components, as changes will be reflected in the master Fleet EE (scratchpad) and fleetdm.com (current, dev-ready) Figma docs.
**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
The following describes how to go about publishing and editing content at Fleet.
@ -321,97 +347,14 @@ 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 |
### 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).
### For editors
#### In this section
- [How to make edits with GitHub](#how-to-make-edits-with-github)
- [How to edit recently merged pull requests for the handbook](#how-to-edit-recently-merged-pull-requests-for-the-handbook)
- [How to edit Markdown pull requests for the docs](#how-to-edit-markdown-pull-requests-for-the-docs)
- [How to edit articles, release posts, and press releases](#how-to-edit-articles-release-posts-and-press-releases)
- [How to edit social media posts](#how-to-edit-social-media-posts)
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/digital-experience/how-to-submit-and-publish-an-article#review-process).
* To edit an existing article, see [How to make edits with GitHub](https://fleetdm.com/handbook/digital-experience#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.
Refer to [Posting on social media as Fleet](https://fleetdm.com/handbook/growth#posting-on-social-media-as-fleet) for details on editing draft social media posts.
Making edits to published social media posts gets a little tricky. Twitter, for example, doesn't allow editing of tweets, so the only way to make an edit is to remove the tweet and post it again.
1. Post the tweet in the #g-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.
Check the [Editor's page](./editor-guide) for everything you need to know to reach editor bliss at Fleet.
### 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.
### Brand resources
To download official Fleet logos, product screenshots, and wallpapers, head over to our [brand resources](https://fleetdm.com/logos) page.
See also [https://fleetdm.com/handbook/community#press-releases](https://fleetdm.com/handbook/community#press-releases) for our press-release boilerplate.
### Email blasts
Do you need to send out a branded email blast to multiple recipients?
@ -472,403 +415,13 @@ Once you have the above follow these steps:
- HTML elements in the Markdown file can cause rendering issues when previewing the generated email. If you see a "Script error" overlay while trying to preview an email, reach out to [Eric Shaw](https://github.com/eashaw) for help.
- The filename of the generated email will have periods changed to dashes. e.g., The generated email partial for `fleet-4.19.0.md` would be `fleet-4-19-0.ejs`
### Using Figma
## Website
We use Figma for most of our design work. This includes the Fleet product, our website, and our marketing collateral.
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.
#### Which file should I use?
**Fleet product** All product design work is done in the [Fleet EE (scratchpad)](https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=9209%3A302838) Figma doc. Check out the [README](https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=2750%3A67203) for how to use this doc.
**Fleet website.** All website design work is done in the [fleetdm.com (current, dev-ready)](https://www.figma.com/file/yLP0vJ8Ms4GbCoofLwptwS/%E2%9C%85-fleetdm.com-(current%2C-dev-ready)?node-id=794%3A373) Figma file.
**Design system.** Shared logos, typography styles, and UI components can be found in [Design system](https://www.figma.com/files/project/15701210).
> The Figma docs in Design System contain the master components that are referenced throughout all other Figma files. Use caution when modifying these components, as changes will be reflected in the master Fleet EE (scratchpad) and fleetdm.com (current, dev-ready) Figma docs.
**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).
> Looking for the official Fleet logo? Download it from: https://fleetdm.com/logos.
### Fleet website
The Brand team is responsible for production and maintenance of the Fleet website.
### Updating Fleet docs and FAQ
- [Tracking](#tracking)
- [How to request a review for Markdown changes to the docs](#how-to-request-a-review-for-markdown-changes-to-the-docs)
- [Markdown](#markdown)
- [Adding links](#adding-links)
- [Linking to a location on GitHub](#linking-to-a-location-on-github)
- [How to fix a broken link](#how-to-fix-a-broken-link)
- [Page order](#page-order)
- [Adding an image](#adding-an-image)
- [Adding a mermaid diagram](#adding-a-mermaid-diagram)
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).
#### How to request a review for Markdown changes to the docs
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
Fleet's documentation and handbook are written in [Markdown](https://about.gitlab.com/handbook/markdown-guide/). Using Markdown lets us keep our documentation consistently formatted and viewable directly from the Fleet GitHub repo. The Markdown files in the `/docs` and `/handbook` folders are converted to HTML for the Fleet website.
When making changes to the Fleet docs or handbook, there are a few differences in how the Markdown will render on GitHub and the Fleet website.
##### Linebreaks and newlines
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 to the docs:
```
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
##### Ordered lists
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.
For example, this list:
```
1. Item one
Paragraph about item one
2. Item two
```
On the Fleet website, this ordered list would be rendered as
1. Item one
Paragraph about item one
2. Item two
To make sure that ordered lists increment on the Fleet website, you can indent the content nested within the list. For example, the same ordered list with indentation:
```
1. Item one
Paragraph about item one
2. Item two
```
This ordered list will render correctly as
1. Item one
Paragraph about item one
2. Item two
#### Adding 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.
#### How to fix 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.
#### 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 `<meta name="pageOrderInSection" value="150">` to the page.
#### Adding an image
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.
#### Adding a mermaid diagram
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
```
### Wireframes
Before committing anything to code, we create wireframes to illustrate all changes that affect the website layout and structure.
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.
#### 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
#### 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 |
#### When can I merge a change to the website?
When merging a PR to master, remember that whatever you merge to master gets deployed live immediately. So if the PR's changes contain anything that you don't think is appropriate to be seen publicly by all guests of [fleetdm.com](https://fleetdm.com/), please do not merge.
Merge a PR (aka deploy the website) when you think it is appropriately clean to represent our brand. When in doubt, use the standards and quality seen on existing pages, ensure correct functionality, and check responsive behavior - starting widescreen and resizing down to ≈320px width.
#### How can I test changes to the website?
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/admin/email-preview)
> 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`.
#### How can I create a new landing page?
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.
#### Maintaining browser compatibility
A browser compatibility check of [fleetdm.com](https://fleetdm.com/) should be carried out monthly to verify that the website looks and functions as expected across all [supported browsers](../../docs/Using-Fleet/Supported-browsers.md).
- 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.
#### 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.
#### 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.
#### 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.
#### How to make usability changes to the website
We want to make it easy to learn how to manage devices with Fleet. Anyone inside or outside the company can suggest changes to the website to improve ease of use and [clarity](http://selmiak.bplaced.net/games/pc/index.php?lang=eng&game=Loom&page=Audio-Drama--Game-Script#:~:text=Above%20all%20else%20...%20clarity.).
To propose changes:
1. Decide what you want to change. A small change is the best place to start.
2. Wireframe the design. Usually, the Brand team does this, but anyone can contribute.
3. Present your change to the website DRI. They will approve it or suggest revisions.
4. Code the website change. Again, the Brand team often does this, but anyone can help.
5. Measure if the change made it easier to use. This can be tricky, but the marketing team will have ideas on how to do this.
#### 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.
## Documentation
The [Docs handbook](./docs-handbook) details processes specific to updating and maintaining the Fleet docs.
## Rituals
@ -917,9 +470,6 @@ To plan or propose a change to the website, or to submit a bug report about the
> _**Note:** One important exception is changes to the website that accompany changes in the core product. These are instead handled by the [Customer Experience group](https://fleetdm.com/handbook/company/product-groups#customer-experience-group), and should be [proposed as changes to the core product](https://fleetdm.com/handbook/product#intake)._
#### Website roadmap
You can see [planned changes to the website](https://app.zenhub.com/workspaces/g-website-6451748b4eb15200131d4bab/board?sprints=none). All groups at Fleet share the same release schedule for iterations (sprints).
### Other requests
To make any other kind of request from the marketing department, or if you are unsure, then post in our group Slack channel (`#g-marketing`) and someone from this group will reply within 1 business day. Please only at-mention specific contributors in time-sensitive situations, or when their personal attention is required.
@ -931,12 +481,12 @@ 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-website` | Mike Thomas |
| `#g-website` | Michael Thomas |
| `#fleet-mindshare-pr` | Jarod Reyes |
| `#help-public-relations` | Jarod Reyes |
| `#help-promote` | Jarod Reyes |
| `#help-swag` | Drew Baker |
| `#oooh-websites` | Mike Thomas |
| `#oooh-websites` | Michael Thomas |
| `#help-p1` | Mike McNeil |

2
handbook/marketing/commonly-used-terms.md
View file

@ -64,5 +64,5 @@ This glossary provides definitions to commonly used terms within our space.
| **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. |
<meta name="maintainedBy" value="desmi-dizney">
<meta name="maintainedBy" value="mike-j-thomas">
<meta name="title" value="Commonly used terms">

1
handbook/marketing/content-style-guide.md
View file

@ -301,6 +301,7 @@ Give an overview of the topic. You don’t need to mention everything at the beg
#### 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.

133
handbook/marketing/docs-handbook.md Normal file
View file

@ -0,0 +1,133 @@
# 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.[Markdown](https://about.gitlab.com/handbook/markdown-guide/). 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 `<meta name="pageOrderInSection" value="150">` 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
```
<meta name="maintainedBy" value="mike-j-thomas">
<meta name="title" value="Docs handbook">

70
handbook/marketing/editor-guide.md Normal file
View file

@ -0,0 +1,70 @@
# 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](./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.
<meta name="maintainedBy" value="mike-j-thomas">
<meta name="title" value="Editor guide">

74
handbook/marketing/markdown-guide.md
View file

@ -1,5 +1,9 @@
# 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.
@ -20,6 +24,36 @@ Try to stay within three or four heading levels. Complicated documents may use m
| `***Bold italic***` | <em><strong>Bold italic</strong></em> |
| `~~Strikethrough~~` | <s>Strikethrough</s> |
## 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
@ -29,6 +63,46 @@ Try to stay within three or four heading levels. Complicated documents may use m
| <pre>1. Line one<br>2. Line two <br>3. Line three<br>4. Line four</pre> | 1. Line one<br>2. Line two<br> 3. Line three<br>4. Line four |
| <pre>1. Line one<br>1. Indent one<br>2. Line two<br>3. Line three<br>1. Indent one<br>2. Indent two<br>4. Line four</pre> | 1. Line one<br>&nbsp;1. Indent one<br>2. Line two<br>3. Line three<br>&nbsp;1. Indent one<br>&nbsp;2. Indent two<br>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 |

234
handbook/marketing/website-handbook.md Normal file
View file

@ -0,0 +1,234 @@
# 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:
- [Documentation](https://fleetdm.com/handbook/marketing#documentation)
- [Publishing an article](./how-to-submit-and-publish-an-article)
- [Markdown guide](./markdown-guide)
## 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"](http://localhost:2024/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
Before estimating changes to the website, 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/admin/email-preview)
> **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 master 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.
<meta name="maintainedBy" value="mike-j-thomas">
<meta name="title" value="Website handbook">