From 52e22014a9396ba5477d6e2cec2521c5fca1d948 Mon Sep 17 00:00:00 2001 From: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com> Date: Thu, 28 Jul 2022 16:33:49 +0900 Subject: [PATCH] re-organized digital experience handbook page (#6933) - moved Article formatting guidelines to their own page - moved glossary of terms to its own page --- handbook/digital-experience/README.md | 199 +----------------- .../article-formatting-guidelines.md | 138 ++++++++++++ .../digital-experience/commonly-used-terms.md | 68 ++++++ 3 files changed, 207 insertions(+), 198 deletions(-) create mode 100644 handbook/digital-experience/article-formatting-guidelines.md create mode 100644 handbook/digital-experience/commonly-used-terms.md diff --git a/handbook/digital-experience/README.md b/handbook/digital-experience/README.md index 0f3a4828e9..902316a87d 100644 --- a/handbook/digital-experience/README.md +++ b/handbook/digital-experience/README.md @@ -276,67 +276,7 @@ When deciding whether to describe Fleet as open source or open core, define who ## Commonly used terms -| 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. | +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 @@ -344,7 +284,6 @@ To download official Fleet logos, product screenshots, and wallpapers, head over 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? @@ -442,142 +381,6 @@ In Figma: 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. -## Article formatting guidelines - -To publish an article, you will need to create a Pull Request for a new file, formatted in Markdown (todo), in [https://github.com/fleetdm/fleet/tree/main/articles](https://github.com/fleetdm/fleet/tree/main/articles). - -#### On this page -- [Layout](#layout) -- [Images and screenshots](#images-and-screenshots) -- [Meta tags](#meta-tags) -- [Customizable CTA](#customizable-cta) -- [Other pages of interest](#other-pages-of-interest) - -### Layout -The following layout guide aims to help you create consistently formatted articles. For an existing article example, check out the [Markdown](https://raw.githubusercontent.com/fleetdm/fleet/main/articles/tales-from-fleet-security-speeding-up-macos-updates-with-nudge.md) and the [finished result](https://fleetdm.com/securing/tales-from-fleet-security-speeding-up-macos-updates-with-nudge). - -#### Hero image -Consider adding a hero image for a more significant impact. Get in touch with Digital Experience via #content on Slack to make a request. - -#### Table of contents -For long articles or guides, consider adding a table of contents. - -#### Introduction -It’s good practice to start your article with a clear summary of what you will be discussing. - -#### Main content -The main body of your article. - -#### Conclusion -It’s a good idea to finish your article with a clear closing statement. - -#### Add a customizable CTA -Add a CTA at the end of your article. See [Customizable CTA](#customizable-cta) below for instructions on creating a CTA tailored to your article topic. - -### Images and screenshots -Images are a great way to help engage your readers. But consider the following before including images or screenshots in your article: - -- Does the image add value? -- Is your image likely to go out of date soon? (Consider the long-term maintenance of your article.) - -### Meta tags -These tags help pass information to the website about the article to display and store it. - -``` - - - - - - -``` - -#### `articleTitle` -The title of your article. Avoid long titles. As a rule of thumb, your title should not exceed two lines at desktop browser resolution. This is roughly 75 characters (including spaces). - -#### `authorFullName` -Add the author’s full name here. Our system does not currently support multiple authors. - -#### `authorGitHubUsername` -Add the author’s GitHub username to populate the author’s headshot. - -#### `category` -Choose only __one__ of the following categories for your article. - -- __Announcements__: company or product announcements (including breaking changes), news, or events. -- __Engineering__: posts about engineering at Fleet and other engineering-related topics. -- __Guides__: help articles for using and deploying Fleet. -- __Podcasts__: podcast-related posts. -- __Product__: posts related to Fleet features. -- __Releases__: release posts, security, and patch releases. -- __Reports__: posts about the industry, data, surveys, etc. -- __Security__: posts about how we approach security at Fleet and other security-related topics. -- Success stories: stories from users or customers successfully using Fleet. - -#### `publishedOn` -The date that the article was published. Please follow the correct date format, e.g., __2021-09-29__. - -#### `articleImageUrl` -The relative url path for the article cover image. Article images are stored in `../website/assets/images/articles/` See [How to export images for the website](https://fleetdm.com/handbook/brand#how-to-export-images-for-the-website). - -### Customizable CTA -Use the following code snippet to include an inline CTA (call to action) in your article: - -``` - - -``` - -![Customizable CTA example](../images/cta-example-1-900x320@2x.jpg) - -> __Tip__: paste the code-snippet at the end of your article, or, when creating long articles, consider adding a CTA mid-way through. - -#### How to modify the customizable CTA -You can customize the CTA to promote what's relevant to your article. - -##### `title` -The main call to action text - -##### `text` -The proposition statement for your call to action - -##### `primary-button-text` -The main call to action interaction. E.g., “Get started.” - -##### `primary-button-href` -The URL link for your primary CTA. - -##### `secondary-button-text` (optional) -The secondary call to action interaction. E.g., “Schedule a demo.” - -##### `secondary-button-href` -The URL link for your secondary CTA. - -#### Example -In the following example we will modify `title`, `text`, `primary-button-text`, and also remove `secondary-button-text` and `secondary-button-href` to create a call to action that promotes a job opening at Fleet. - -``` - -``` - -![Customizable CTA example](../images/cta-example-2-900x280@2x.jpg) - -### Other pages of interest -- [Process for submitting and publishing articles](https://docs.google.com/document/d/1owejJ7PjCVm0e21QNXjzw7SRMa3FdkRxb8WoHkKxWRE/edit?usp=sharing) -- Markdown guide (todo) -- Writing style guide (todo) - ## Rituals The following table lists the Brand group's rituals, frequency, and Directly Responsible Individual (DRI). diff --git a/handbook/digital-experience/article-formatting-guidelines.md b/handbook/digital-experience/article-formatting-guidelines.md new file mode 100644 index 0000000000..eb1bf6ce7d --- /dev/null +++ b/handbook/digital-experience/article-formatting-guidelines.md @@ -0,0 +1,138 @@ +# Article formatting guidelines + +To publish an article, you will need to create a Pull Request for a new file, formatted in Markdown (todo), in [https://github.com/fleetdm/fleet/tree/main/articles](https://github.com/fleetdm/fleet/tree/main/articles). + +### On this page +- [Layout](#layout) +- [Images and screenshots](#images-and-screenshots) +- [Meta tags](#meta-tags) +- [Customizable CTA](#customizable-cta) +- [Other pages of interest](#other-pages-of-interest) + +## Layout +The following layout guide aims to help you create consistently formatted articles. For an existing article example, check out the [Markdown](https://raw.githubusercontent.com/fleetdm/fleet/main/articles/tales-from-fleet-security-speeding-up-macos-updates-with-nudge.md) and the [finished result](https://fleetdm.com/securing/tales-from-fleet-security-speeding-up-macos-updates-with-nudge). + +### Hero image +Consider adding a hero image for a more significant impact. Get in touch with Digital Experience via #content on Slack to make a request. + +### Table of contents +For long articles or guides, consider adding a table of contents. + +### Introduction +It’s good practice to start your article with a clear summary of what you will be discussing. + +### Main content +The main body of your article. + +### Conclusion +It’s a good idea to finish your article with a clear closing statement. + +### Add a customizable CTA +Add a CTA at the end of your article. See [Customizable CTA](#customizable-cta) below for instructions on creating a CTA tailored to your article topic. + +## Images and screenshots +Images are a great way to help engage your readers. But consider the following before including images or screenshots in your article: + +- Does the image add value? +- Is your image likely to go out of date soon? (Consider the long-term maintenance of your article.) + +## Meta tags +These tags help pass information to the website about the article to display and store it. + +``` + + + + + + +``` + +### `articleTitle` +The title of your article. Avoid long titles. As a rule of thumb, your title should not exceed two lines at desktop browser resolution. This is roughly 75 characters (including spaces). + +### `authorFullName` +Add the author’s full name here. Our system does not currently support multiple authors. + +### `authorGitHubUsername` +Add the author’s GitHub username to populate the author’s headshot. + +### `category` +Choose only __one__ of the following categories for your article. + +- __Announcements__: company or product announcements (including breaking changes), news, or events. +- __Engineering__: posts about engineering at Fleet and other engineering-related topics. +- __Guides__: help articles for using and deploying Fleet. +- __Podcasts__: podcast-related posts. +- __Product__: posts related to Fleet features. +- __Releases__: release posts, security, and patch releases. +- __Reports__: posts about the industry, data, surveys, etc. +- __Security__: posts about how we approach security at Fleet and other security-related topics. +- Success stories: stories from users or customers successfully using Fleet. + +### `publishedOn` +The date that the article was published. Please follow the correct date format, e.g., __2021-09-29__. + +### `articleImageUrl` +The relative url path for the article cover image. Article images are stored in `../website/assets/images/articles/` See [How to export images for the website](https://fleetdm.com/handbook/brand#how-to-export-images-for-the-website). + +## Customizable CTA +Use the following code snippet to include an inline CTA (call to action) in your article: + +``` + + +``` + +![Customizable CTA example](../../images/cta-example-1-900x320@2x.jpg) + +> __Tip__: paste the code-snippet at the end of your article, or, when creating long articles, consider adding a CTA mid-way through. + +### How to modify the customizable CTA +You can customize the CTA to promote what's relevant to your article. + +#### `title` +The main call to action text + +#### `text` +The proposition statement for your call to action + +#### `primary-button-text` +The main call to action interaction. E.g., “Get started.” + +#### `primary-button-href` +The URL link for your primary CTA. + +#### `secondary-button-text` (optional) +The secondary call to action interaction. E.g., “Schedule a demo.” + +#### `secondary-button-href` +The URL link for your secondary CTA. + +### Example +In the following example we will modify `title`, `text`, `primary-button-text`, and also remove `secondary-button-text` and `secondary-button-href` to create a call to action that promotes a job opening at Fleet. + +``` + +``` + +![Customizable CTA example](../../images/cta-example-2-900x280@2x.jpg) + +## Other pages of interest +- [Process for submitting and publishing articles](https://docs.google.com/document/d/1owejJ7PjCVm0e21QNXjzw7SRMa3FdkRxb8WoHkKxWRE/edit?usp=sharing) +- Markdown guide (todo) +- Writing style guide (todo) + + + \ No newline at end of file diff --git a/handbook/digital-experience/commonly-used-terms.md b/handbook/digital-experience/commonly-used-terms.md new file mode 100644 index 0000000000..dd66a6a380 --- /dev/null +++ b/handbook/digital-experience/commonly-used-terms.md @@ -0,0 +1,68 @@ +# 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. | + + +