diff --git a/public/__redirects b/public/__redirects index 82ecccc6e16b91f..cfbedbc7c0436cd 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1311,6 +1311,14 @@ /stream/platform/ /stream/changelog/ 301 /stream/reference/ /stream/faq/ 301 +# style guide + +/docs-guide/manage-content/redirects/ /style-guide/how-we-docs/redirects/ 301 +/docs-guide/manage-content/redirects/best-practices/ /style-guide/how-we-docs/redirects/ 301 +/docs-guide/manage-content/redirects/process/ /style-guide/how-we-docs/redirects/ 301 +/docs-guide/manage-content/metadata/ /style-guide/how-we-docs/metadata/ 301 +/docs-guide/manage-content/metadata/process/ /style-guide/how-we-docs/metadata/ 301 + # support /support/about-cloudflare/getting-started/troubleshooting-faq-for-new-cloudflare-customers/ /fundamentals/reference/troubleshooting/ 301 diff --git a/src/assets/images/style-guide/how-we-docs/intellisense.png b/src/assets/images/style-guide/how-we-docs/intellisense.png new file mode 100644 index 000000000000000..d9a23994027d518 Binary files /dev/null and b/src/assets/images/style-guide/how-we-docs/intellisense.png differ diff --git a/src/assets/images/style-guide/how-we-docs/redirects-github.png b/src/assets/images/style-guide/how-we-docs/redirects-github.png new file mode 100644 index 000000000000000..795ac3c4758ed79 Binary files /dev/null and b/src/assets/images/style-guide/how-we-docs/redirects-github.png differ diff --git a/src/content/docs/docs-guide/manage-content/metadata/index.mdx b/src/content/docs/docs-guide/manage-content/metadata/index.mdx deleted file mode 100644 index 0d97190cb4ddfa3..000000000000000 --- a/src/content/docs/docs-guide/manage-content/metadata/index.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -pcx_content_type: overview -title: Metadata - ---- - -import { DirectoryListing } from "~/components" - -Page-level metadata - content type, associated products, last updated, word count - lets you take a broader, more strategic view of your content. - -It helps you answer questions like the following: - -* As a writer: - * Am I missing something obvious in the content strategy? - * What are some pages I should be updating right now? -* As a manager: - * Are we over or underinvesting in a specific product area? Or a specific content type? - * How does the traffic to this set of products compare to another? - * How can I communicate broader trends to my stakeholders? - -You cannot answer these questions without some level of rollup reporting, which you can only get through metadata. - -## Resources - - diff --git a/src/content/docs/docs-guide/manage-content/metadata/process.mdx b/src/content/docs/docs-guide/manage-content/metadata/process.mdx deleted file mode 100644 index 970ccea4d566bea..000000000000000 --- a/src/content/docs/docs-guide/manage-content/metadata/process.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -pcx_content_type: reference -title: How we do it -sidebar: - order: 1 -head: - - tag: title - content: Metadata | How we do it - ---- - -At Cloudflare, we track the following information about each page: - -| Value | Description | Examples | -| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | -| **Product** | The top-level subfolder of the page. | `dns`, `bots` | -| **Product Group** | The primary area that each product falls into. | `Application Performance`, `Developer Platform` | -| **Content type** | The primary purpose of the page, which corresponds to our listed [content types](/style-guide/documentation-content-strategy/content-types/). | `how-to`, `faq` | -| **Last modified** | How many days ago was this page last updated? | `63` | -| **Last reviewed** | How many days ago was this page last reviewed? | `100` | -| **Word count** | How many words does the page contain (rounded to the nearest hundred)? | `100` | - -Of all of these values, there is a bit of nuance to our **Last reviewed** metadata. **Last reviewed** differs from **Last modified** because a review is more thorough than an update. A review implies that all contents of the page have been vetted for accuracy. - -Because of this extra effort, we only track **Last reviewed** for content types that are particularly important to the user journey and require an additional level of maintenance. At the moment, those content types are [tutorials](/style-guide/documentation-content-strategy/content-types/tutorial/) and specific types of [configurations](/style-guide/documentation-content-strategy/content-types/configuration/). - -*** - -## Implementation - -There are two aspects to our metadata implementation: how we set these values and how we make them available. - -### Setting values - -In setting values, we automate what we can and manually set the rest: - -| Value | Method | -| ----------------- | ------------------------------------------------------------------------------------------ | -| **Product** | Set automatically by using the subfolder. | -| **Product Group** | Defined at the product level and then automatically applied to each page in the subfolder. | -| **Content type** | Manually set for each page. | -| **Last modified** | Automatically pulled from the Git history. | -| **Last reviewed** | Manually set for some pages. | -| **Word count** | Automatically generated during build time. | - -### Making values available - -We choose to render all of these values as specific `meta` properties for each page. - -This decision - combined with the multiple web scrapers that crawl our pages - means that our metadata is available for reporting and search improvements (ranking and faceting). - -It also means that our GitHub repo is always the source of truth and we do not have to keep a spreadsheet or mapping updated elsewhere. diff --git a/src/content/docs/docs-guide/manage-content/redirects/best-practices.mdx b/src/content/docs/docs-guide/manage-content/redirects/best-practices.mdx deleted file mode 100644 index 2a66411b840f3a3..000000000000000 --- a/src/content/docs/docs-guide/manage-content/redirects/best-practices.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -pcx_content_type: reference -title: Best practices -sidebar: - order: 3 -head: - - tag: title - content: Redirects | Best practices ---- - -Beyond [how Cloudflare uses redirects](/docs-guide/manage-content/redirects/process/), we follow these best practices. - -## Organize your redirects - -As much as you can, try to organize your redirects into logical groups (products, alphabetical order). This process helps prevent duplicate redirects, as well as identifying specific ones you might be looking for. - -In our [Pages `_redirects` file](https://github.com/cloudflare/cloudflare-docs/blob/production/public/_redirects), we use extensive comments, separating different product areas. We also try, as much as we can, to keep the redirects in alphabetical order within a section. - -We used to apply a similar principle to [Bulk Redirect lists](/rules/url-forwarding/bulk-redirects/) (when that was our primary method). We created lists that grouped together similar products and labeled them as such, so it was easier to find which redirect you were looking for. - -## Know what you can redirect - -At the server level, you can trigger a redirect on a URL path (`/page/`), but not a fragment (`/page/#fragment`). - -You can redirect a page to a fragment, however (`/page1/` to `/page2/#fragment`). - -## Use automation - -Particularly in an open-source environment, use automation to identify changes that might require redirects. We built a [GitHub action](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/comment-changed-filenames.yml) specifically for this use case. - -You should apply a similar process to infinite redirects (where two redirect rules point to each other), if possible, and redirects containing a source URL fragment, which are invalid. We have a [dedicated script](https://github.com/cloudflare/cloudflare-docs/blob/production/bin/validate-redirects.ts) to check for these situations in our Pages project. diff --git a/src/content/docs/docs-guide/manage-content/redirects/index.mdx b/src/content/docs/docs-guide/manage-content/redirects/index.mdx deleted file mode 100644 index edd7c072e52571a..000000000000000 --- a/src/content/docs/docs-guide/manage-content/redirects/index.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -pcx_content_type: overview -title: Redirects - ---- - -import { DirectoryListing, GlossaryTooltip } from "~/components" - -As your content changes (and it will change), redirects preserve continuity for your users and (friendly) bots. - -The most obvious part of this is the user experience. If you click a link in the dashboard or use a bookmarked URL, you trust that it's taking you to the right place. Not a `404` page or the wrong page, but the right page. Redirects help direct users to the right place. - -The same applies to the automated experience. If you move a page without redirects, you are losing the historical search authority that Google and other search engines use to rank your page. - -## Resources - - diff --git a/src/content/docs/docs-guide/manage-content/redirects/process.mdx b/src/content/docs/docs-guide/manage-content/redirects/process.mdx deleted file mode 100644 index 73d0be3e5c39a24..000000000000000 --- a/src/content/docs/docs-guide/manage-content/redirects/process.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -pcx_content_type: reference -title: How we do it -sidebar: - order: 1 -head: - - tag: title - content: Redirects | How we do it ---- - -There are [multiple ways](https://developers.google.com/search/docs/crawling-indexing/301-redirects) of performing redirects, including at your server, client-side redirects, and using a CDN. - -We use various Cloudflare products for our redirects, due to ease of use and speed[^1]. - -[^1]: Performing redirects through Cloudflare lets you implement redirects on the Cloudflare global network instead of making requests travel all the way to an origin server. - -## How we add redirects - -### Cloudflare Pages (primary) - -Our primary method takes advantage of the [Pages platform](/pages/configuration/redirects/), defining redirects in a [plain text file](https://github.com/cloudflare/cloudflare-docs/blob/production/public/_redirects) in our GitHub repo. - -This setup allows us to use the same workflow for redirects as for any other documentation change. We implement a redirect in the same pull request as the content change and can test these changes in our preview branches. - -We also love the flexibility provided by the [Pages syntax](/pages/configuration/redirects/#advanced-redirects). - -### Bulk redirects (secondary) - -In certain situations, we also use [Bulk redirects](/rules/url-forwarding/bulk-redirects/). - -Normally, bulk redirects only come up when another team is adding a large number of individual redirects to our site, such as when all of our previous `support.cloudflare.com` content was migrated and needed individualized redirects per locale. - -We use this method when the contributors are outside of our team and when the total number of redirects is so large that it would clutter our `_redirects` file and count against our [limit for Pages redirects](/pages/configuration/redirects/#surpass-_redirects-limits). - ---- - -## When we add redirects - -Our team adds redirects in two situations: during the course of normal content and as needed based on data. - -### During content work - -During normal content work, you want to add redirects when you do the following to a page: - -- Change any part of the URL (filename, folder). -- Delete the page. - -We have some automation to help [flag needed redirects](/docs-guide/manage-content/automation/process/#contributor-resources). - -### Based on data - -Another time to add redirects is when you see a lot of `404` response codes on certain paths of your docs site. These `404` responses might be due to a missing redirect or mistyped link. - -We identify these status codes either through our [Cloudflare analytics](/analytics/account-and-zone-analytics/zone-analytics/) (ad hoc) or [Logpush job](/logs/about/) (more thorough, quarterly). diff --git a/src/content/docs/style-guide/api-content-strategy/index.mdx b/src/content/docs/style-guide/api-content-strategy/index.mdx index c054d35166d5da3..b02a892197de0fa 100644 --- a/src/content/docs/style-guide/api-content-strategy/index.mdx +++ b/src/content/docs/style-guide/api-content-strategy/index.mdx @@ -1,18 +1,17 @@ --- pcx_content_type: concept -title: API content strategy +title: API docs content strategy sidebar: order: 5 - --- -import { DirectoryListing } from "~/components" +import { DirectoryListing } from "~/components"; -The API content strategy aims to: +The API docs content strategy aims to: -* Reduce internal and external user frustration -* Align with industry standards in terms of naming conventions and descriptions -* Create world-class content that is just as good, or better, than very popular API documentation +- Reduce internal and external user frustration +- Align with industry standards in terms of naming conventions and descriptions +- Create world-class content that is just as good, or better, than very popular API documentation By ensuring Cloudflare's API content is straightforward, easy to navigate, and consistent, we can create world-class API content that eliminates user frustration and serves as an example of good API documentation. diff --git a/src/content/docs/style-guide/components/mermaid.mdx b/src/content/docs/style-guide/components/mermaid.mdx index d8a2b5f415c5785..5b631bb09a1bcae 100644 --- a/src/content/docs/style-guide/components/mermaid.mdx +++ b/src/content/docs/style-guide/components/mermaid.mdx @@ -4,6 +4,12 @@ title: Mermaid Mermaid diagrams are added with [`remark-mermaid`](https://github.com/remcohaszing/rehype-mermaid/) and [`mermaid`](https://www.npmjs.com/package/mermaid). +## Guidelines + +Use Mermaid diagrams to illustrate product or process flows. If they work for your use case, Mermaid diagrams are preferable to other [diagrams](/style-guide/documentation-content-strategy/component-attributes/diagrams/) because they are more easily searchable and changeable. + +## Usage + ```mermaid flowchart LR accTitle: Tunnels diagram @@ -40,4 +46,9 @@ E[Anycast IP] --> F[/Tunnel 1 /
priority 1/] --> I{{Customer
data ce E[Anycast IP] --> G[/Tunnel 2 /
priority 1/] --> J{{Customer
data center/
network 2}} E[Anycast IP] --> H[/Tunnel 3 /
priority 2/] --> K{{Customer
data center/
network 3}} ``` -```` \ No newline at end of file +```` + +## Related components + +- [Diagrams](/style-guide/documentation-content-strategy/component-attributes/diagrams/) +- [Screenshots](/style-guide/documentation-content-strategy/component-attributes/screenshots/) diff --git a/src/content/docs/style-guide/documentation-content-strategy/component-attributes/diagrams.mdx b/src/content/docs/style-guide/documentation-content-strategy/component-attributes/diagrams.mdx index 6f4d8e2c7bdfc92..fe4e2bd05369a70 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/component-attributes/diagrams.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/component-attributes/diagrams.mdx @@ -1,12 +1,11 @@ --- pcx_content_type: concept title: Diagrams - --- ## Definition -Images that depict a process, architecture, or some other form of technology. +Images that depict a process, architecture, or some other form of technology. These should ideally be in an `SVG` format because of scalability issues. ## Used in @@ -20,7 +19,6 @@ Diagrams explain complex topics in a compelling way and help users visualize a s ```md ![Alt text](/link/to/image.svg "Caption to go under the image") - ``` ## Example @@ -32,3 +30,12 @@ Diagrams explain complex topics in a compelling way and help users visualize a s Always try to use SVG images for diagrams. Bitmap formats like PNG and JPEG do not scale well, and often users will zoom into diagrams to explore the details. The alt (alternative) text on diagrams is used by screen readers and is read out as part of the surrounding content. Ensure the alt text is straightforward and fits in the context of the content. + +## Optimizations + +When we use SVGs for diagrams, we can also optimize them via a [recurring script](https://github.com/cloudflare/cloudflare-docs/blob/production/scripts/optimize-svgs.ts) in our repo. + +## Related components + +- [Mermaid diagrams](/style-guide/components/mermaid/) +- [Screenshots](/style-guide/documentation-content-strategy/component-attributes/screenshots/) diff --git a/src/content/docs/style-guide/documentation-content-strategy/component-attributes/links.mdx b/src/content/docs/style-guide/documentation-content-strategy/component-attributes/links.mdx index 67d4efc3244d377..7564b4b5a9db849 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/component-attributes/links.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/component-attributes/links.mdx @@ -1,38 +1,37 @@ --- pcx_content_type: concept title: Links - +meta: + title: Links | Component attributes --- -## Definition - -Reference to data that can be accessed by clicking, tapping, or selecting. +import { Render } from "~/components"; -## Used in +A link is a reference to another page, part of a page, or external resource. -All content types +Hyperlinks are incredibly useful but - if overdone - can be distracting. -## Overview +## Types of links -Hyperlinks are incredibly useful in online content but should not be overdone. Excessive hyperlinking inside of paragraphs is often distracting and can deviate the reader's focus from the piece at hand. + ## Guidance for inline paragraph links -Avoid non-descriptive link text like: click here and this page; instead, use the actual title of the target page or an abbreviated version of that title. This is also important so that readers see that when they get there, they actually linked to the page they intended to visit. +Avoid non-descriptive link text like: `click here` and `this page`; instead, use the actual title of the target page or an abbreviated version of that title. This is also important so that readers see that when they get there, they actually linked to the page they intended to visit. Use unique link text. Speech recognition software does not handle duplicated link text well. -Use in-paragraph links only if they are internal (those within Cloudflare's websites) and if the material relates directly to what's being described. In other words, will the content behind the link help the reader make a decision or accomplish something before continuing to read the current document? +Use in-paragraph links only if they are internal (those within Cloudflare's websites) and if the material relates directly to what's being described. In other words, will the content behind the link help the reader make a decision or accomplish something before continuing to read the current document? Avoid directional language. ## Links for the Related resources section -Use a *Related resources* section at the end of your document for: +Use a _Related resources_ section at the end of your document for: -* Internal links that loosely relate to the topic or offer a chance for deeper learning -* All external links (not residing in Cloudflare's websites) -* Internal and external links that represent the next logical steps to follow +- Internal links that loosely relate to the topic or offer a chance for deeper learning +- All external links (not residing in Cloudflare's websites) +- Internal and external links that represent the next logical steps to follow External links placed in-paragraph are strongly discouraged because Cloudflare has no control over them. For example, if a link no longer resolves, our content feels less reliable. By shifting all external links to the end of the document, the impact of a broken link is less dramatic. @@ -42,6 +41,10 @@ Place links for example requests and API calls in code blocks. Use placeholders in links with account- or user-specific information. And explain what to replace the referential text with. -* For example, for the link "`https://api.cloudflare.com/client/v4/accounts/a0b1c2d3/rulesets`" use "`https://api.cloudflare.com/client/v4/accounts//rulesets`" and add text to say "replace `` with your Account ID" or similar. +- For example, for the link "`https://api.cloudflare.com/client/v4/accounts/a0b1c2d3/rulesets`" use "`https://api.cloudflare.com/client/v4/accounts//rulesets`" and add text to say "replace `` with your Account ID" or similar. See [angle brackets](/style-guide/formatting/code-conventions-and-format/) in Code Conventions and Formatting. + +## Maintenance + +For more details on how we handle link maintenance, refer to [Link maintenance](/style-guide/how-we-docs/links/). diff --git a/src/content/docs/style-guide/documentation-content-strategy/component-attributes/screenshots.mdx b/src/content/docs/style-guide/documentation-content-strategy/component-attributes/screenshots.mdx new file mode 100644 index 000000000000000..e17e9dd2fd94601 --- /dev/null +++ b/src/content/docs/style-guide/documentation-content-strategy/component-attributes/screenshots.mdx @@ -0,0 +1,62 @@ +--- +pcx_content_type: concept +title: Screenshots +--- + +A screenshot is a picture of a software tool, in this case usually of the Cloudflare dashboard. + +We only recommend screenshots in [specific scenarios](#when-to-use), as they have a higher [maintenance cost](#maintenance) than other types of content. + +## When to use + +Use screenshots sparingly and intentionally. For example, it's appropriate to use a screenshot when the task is simple but often confuses users or is hard to describe with words alone. + +A canonical example of this would be [Find account and zone ID](/fundamentals/account/find-account-and-zone-ids/) because: + +- It's a high driver of SEO traffic to our [Community](https://community.cloudflare.com). +- We tried explaining with words alone and that did not solve the confusion. +- It's a task specifically related to new users, where they are less familiar with Cloudflare concepts or navigation patterns. + +:::note + +Use screenshots liberally in [Changelog entries](/style-guide/documentation-content-strategy/content-types/changelog/), because this content type is an accepted "point-in-time" reference and it's okay for these screenshots to be outdated. + +::: + +## Guidelines + +Screenshots should: + +- Maintain the original aspect-lock ratio. +- Keep resolution at 72dpi. +- Keep width at 500-600 pixels. +- Avoid sharing sensitive information (you may need to edit the underlying HTML in your browser). +- Avoid including visuals that change frequently, such as sidebar navigation. +- Have descriptive alt text. + +## Usage + +```mdx +![Alt text](~/assets/images/$PRODUCT_NAME/$IMAGE_NAME.png) +``` + +Add screenshots to the corresponsding `$PRODUCT_NAME` folder under [`/src/assets/images/`](https://github.com/cloudflare/cloudflare-docs/tree/production/src/assets/images). You may want to add subfolders for organizational purposes. + +## Maintenance + +We avoid screenshots without a clear purpose because they are difficult to maintain. This is because: + +- The UI might change and our team might not know. +- Even if you do know what changed, it's difficult to _find_ which screenshots might reference a particular UI flow. +- If something is changed, you need to fully re-take the screenshot to replace it. This could involve adding fake data or hiding sensitive information. + +:::note + +For more details on how we approach this maintenance, refer to [Image maintenance](/style-guide/how-we-docs/image-maintenance/). + +::: + +## Related components + +- [Diagrams](/style-guide/documentation-content-strategy/component-attributes/diagrams/) +- [Mermaid diagrams](/style-guide/components/mermaid/) diff --git a/src/content/docs/style-guide/documentation-content-strategy/index.mdx b/src/content/docs/style-guide/documentation-content-strategy/index.mdx index a4289119749b16b..9ebd1a8373b3980 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/index.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/index.mdx @@ -1,27 +1,26 @@ --- pcx_content_type: concept -title: Developer documentation content strategy +title: Product docs content strategy sidebar: order: 3 - --- -import { DirectoryListing } from "~/components" +import { DirectoryListing } from "~/components"; The purpose of Cloudflare's developer documentation content strategy is to: -* Create and document standard templates to streamline content creation -* Document specific content types to help identify customers' specific needs -* Enable life cycle management to maintain and optimize a smaller set of pages -* Suggest easier navigation paths +- Create and document standard templates to streamline content creation +- Document specific content types to help identify customers' specific needs +- Enable life cycle management to maintain and optimize a smaller set of pages +- Suggest easier navigation paths Strategically speaking, the mission and guiding principles translate into the following initiatives: -* Improve the entire ecosystem of customer-facing product content, placing major emphasis on consistency, quality, accuracy, and timeliness -* Create a cohesive and compelling story around our products and their functionality -* Develop content that increases product adoption, deflects support, and makes customers successful -* Partner with various internal departments and stakeholders in creating and sustaining a rich, consistent content experience across all Cloudflare products -* Devise new and better ways to give users the information they need, when and where they need it +- Improve the entire ecosystem of customer-facing product content, placing major emphasis on consistency, quality, accuracy, and timeliness +- Create a cohesive and compelling story around our products and their functionality +- Develop content that increases product adoption, deflects support, and makes customers successful +- Partner with various internal departments and stakeholders in creating and sustaining a rich, consistent content experience across all Cloudflare products +- Devise new and better ways to give users the information they need, when and where they need it Adoption of this content strategy will be impacted by product releases, resourcing, and company goals. @@ -33,13 +32,13 @@ This approach includes: ### Information architecture -* Where content should live on the site -* Linking strategy +- Where content should live on the site +- Linking strategy ### Content -* What content is included and what is optional -* How the content is written +- What content is included and what is optional +- How the content is written ## Content requirements diff --git a/src/content/docs/style-guide/how-we-docs/image-maintenance.mdx b/src/content/docs/style-guide/how-we-docs/image-maintenance.mdx new file mode 100644 index 000000000000000..5b7bf70229abdf6 --- /dev/null +++ b/src/content/docs/style-guide/how-we-docs/image-maintenance.mdx @@ -0,0 +1,63 @@ +--- +pcx_content_type: how-to +title: Image maintenance +meta: + title: Image maintenance | How we docs +--- + +import { GitHubCode } from "~/components"; + +Though valuable for user understanding, images are difficult to maintain. We have a few strategies that we use to help make this easier. + +## Guidelines + +We support a few different types of images in our docs, including: + +- [Diagrams](/style-guide/documentation-content-strategy/component-attributes/diagrams/) +- [Mermaid diagrams](/style-guide/components/mermaid/) +- [Screenshots](/style-guide/documentation-content-strategy/component-attributes/screenshots/) + +Of these, we prefer Mermaid diagrams because they are searchable and easily changeable. The "cost" of updating a Mermaid diagram is much lower than re-taking a screenshot or working with a designer to update a diagram. + +## Maintenance + +The best way to improve image maintenance is to avoid using them. + +The other way to streamline maintenance is to remove images that are no longer referenced in your documentation. This pattern becomes particularly helpful if you need to audit images for UI changes or leaked information, because then you are not wasting time looking at unused images too. + +We do that through a combination of GitHub actions. + +### Flag unused images + +We have a specific GitHub action to [flag unused images](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/image-audit.yml). + +What the GitHub action does is: + +1. Finds all `.png` or `.svg` files in our content. +2. Checks to see if those files are referenced in any of our MDX files. +3. Ceates a [GitHub issue](https://github.com/cloudflare/cloudflare-docs/issues/23343) if there are unreferenced files. + +### Evaluate image paths + +In combination with [flagging unused images](#flag-unused-images), we also have logic in our [build process](https://github.com/cloudflare/cloudflare-docs/blob/production/astro.config.ts) to validate image paths. + + + +This line ensures that our custom [Remark plugin](https://github.com/cloudflare/cloudflare-docs/blob/production/src/plugins/remark/validate-images.ts) validates all images paths. If the path does not exist, we throw an error and prevent the site from building. + + + +When paired with [flagging unused images](#flag-unused-images), this path validation ensures that a tech writer can safely delete unused files in a pull request. So long as the site builds correctly, you have only deleted image files that are not referenced anywhere. diff --git a/src/content/docs/style-guide/how-we-docs/index.mdx b/src/content/docs/style-guide/how-we-docs/index.mdx new file mode 100644 index 000000000000000..413901f587f3446 --- /dev/null +++ b/src/content/docs/style-guide/how-we-docs/index.mdx @@ -0,0 +1,19 @@ +--- +pcx_content_type: navigation +title: How we docs +sidebar: + order: 10 +--- + +import { DirectoryListing } from "~/components"; + +This section shares how Cloudflare approaches docs strategically, covering topics like `how we built our site` and `how we think about redirects`. + +The goal is twofold because it: + +- Encourages deep thinking about how we approach things (and if they could be better). +- Contributes back to the open-source ecosystem. We get a lot of benefits from being open source and we want to give back. + +We hope you learn from the topics below. As always, [submit an issue](https://github.com/cloudflare/cloudflare-docs/issues/new) if you find something inaccurate or unclear. + + diff --git a/src/content/docs/style-guide/how-we-docs/links.mdx b/src/content/docs/style-guide/how-we-docs/links.mdx new file mode 100644 index 000000000000000..f6c4b16d4ec6f55 --- /dev/null +++ b/src/content/docs/style-guide/how-we-docs/links.mdx @@ -0,0 +1,71 @@ +--- +pcx_content_type: how-to +title: Links +meta: + title: Links | How we docs +--- + +import { GitHubCode, Render } from "~/components"; + +Though [links](/style-guide/documentation-content-strategy/component-attributes/links/) are an important part of documentation, they also have their own maintenance cost. + +We have a few strategies we use to make link maintenance easier. + +## Link types + + + +For each type of link, we think through a few different aspects of the experience. + +- **External**: + - _Source of truth_: Another site. + - _Why does it break_: Another site changed its content. + - _Customer experience of a break_: `404` page on another site. +- **Internal**: + - _Source of truth_: Your site. + - _Why does it break_: Your site changed its content. + - _Customer experience of a break_: `404` page on your site. +- **Anchor**: + - _Source of truth_: Your site. + - _Why does it break_: Your site changed its content. + - _Customer experience of a break_: Page load on your site. Content might be further down the page or have been moved to another page. + +## Checks + +### Internal links + +Of these three [link types](#link-types), only **Internal** links: + +- Happen _within_ the context of a change to your site's content. +- Universally lead to a bad customer experience (a `404` page). +- Are easily auditable within the current context. + +For these reasons, we choose to make a build **fail** based on broken internal links. For our implementation, we rely on the [Starlight link validator plugin](https://github.com/HiDeoo/starlight-links-validator). + + + +Whether or not we run the link validation depends an environmental variable that we set in our [CI build process](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/ci.yml#L52). + +We also make two intentional decisions about this link auditing: + +- **Absolute links, not relative**: We enforce absolute links (`/style-guide/how-we-docs/metadata/`) and fail on relative links (`../metadata/`) to avoid time-consuming maintenance in the future. This decision also helps with find/replace work and any future platform migrations. +- **No redirects**: We do not consider redirects when evaluating links. We have the current source of truth, so we should utilize that truth to its fullest (as well as helping us avoid redirect chains and future maintenance). + +### External links + +Though external links are not good for the customer experience, they also don't change within the context of a change to your site's content. Additionally, external link checking can be time consuming and error prone, which can slow down contributions. + +We use an external SEO tool to help flag these broken external links for us, addressing them as needed (instead of making a build fail because of them). + +### Anchor links + +Anchor links do not have as dramatic as consequences of being wrong as internal links. If you have a broken anchor link, a customer will either need to manually scroll to the header or - in some cases - go to another page. + +Because of these characteristics, we run [periodic, background checks](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/anchor-link-audit.yml) to flag broken anchor links, using the `htmltest` library. diff --git a/src/content/docs/style-guide/how-we-docs/metadata.mdx b/src/content/docs/style-guide/how-we-docs/metadata.mdx new file mode 100644 index 000000000000000..275bdcfaf7865ac --- /dev/null +++ b/src/content/docs/style-guide/how-we-docs/metadata.mdx @@ -0,0 +1,124 @@ +--- +pcx_content_type: how-to +title: Metadata +meta: + title: Metadata | How we docs +--- + +import { GitHubCode } from "~/components"; + +Page-level metadata - content type, associated products, last updated, word count - lets you take a broader, more strategic view of your content. + +It helps you answer questions like the following: + +- As a writer: + - Am I missing something obvious in the content strategy? + - What are some pages I should be updating right now? + - How does X tutorial compare with all tutorials? Is it getting more traffic than the baseline? +- As a manager: + - Are we over or underinvesting in a specific product area? Or a specific content type? + - How does the traffic to this set of products compare to another? + - How can I communicate broader trends to my stakeholders? + +You cannot answer these questions without some level of rollup reporting, which you can only get through metadata. + +## What we track + +At Cloudflare, we track the following information about different pages: + +| Value | Description | Examples | +| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| **Product** | The top-level subfolder of the page. | `dns`, `bots` | +| **Product Group** | The primary area that each product falls into. | `Application Performance`, `Developer Platform` | +| **Tags** | Specific [atttributes](/style-guide/frontmatter/tags/) related to a page's content or purpose. | `AI`, `JavaScript`, `Headers` | +| **Content type** | The primary purpose of the page, which corresponds to our listed [content types](/style-guide/documentation-content-strategy/content-types/). | `how-to`, `faq` | +| **Last modified** | How many days ago was this page last updated? | `63` | +| **Last reviewed** (optional) | How many days ago was this page last reviewed? | `100` | + +Of all of these values, there is a bit of nuance to our **Last reviewed** metadata. **Last reviewed** differs from **Last modified** because a review is more thorough than an update. A review implies that all contents of the page have been vetted for accuracy. + +Because of this extra effort, we only track **Last reviewed** for content types that are particularly important to the user journey and require an additional level of maintenance. At the moment, those content types are [tutorials](/style-guide/documentation-content-strategy/content-types/tutorial/). + +--- + +## How we track + +We set these values at two different levels, the folder level and the page level. + +### Folder-level attributes + +We set two values at a folder level, `Product` and `Product Group`. We take this approach because we can assume that these values apply every page within that folder. + +For example, here's the content from our [DNS folder](https://github.com/cloudflare/cloudflare-docs/blob/production/src/content/products/dns.yaml). + + + +### Page-level attributes + +We primarily set page-level attributes through the [page's frontmatter](/style-guide/frontmatter/custom-properties/). + +For example, here are the values set for our [Build a Slackbot tutorial](/workers/tutorials/build-a-slackbot/). + + + +However, the `last_modified` value is pulled automatically from the git history of a file. + +--- + +## How we use values + +We choose to render all of these values as specific `meta` properties for each page. + +For example, these are the `meta` properties and values on the [AI Audit - Get Started page](/ai-audit/get-started/). + +{/* prettier-ignore */} +```html title="Get Started | AI Audit" + + + + +``` + +We render these values using a custom override for our [`Head.astro`](https://github.com/cloudflare/cloudflare-docs/blob/production/src/components/overrides/Head.astro) file. If specific values are set, we then add them as meta tags onto the page. + + + +### Benefits + +We get two primary benefits from structuring our content this way. + +First, our metadata is easily consumable by anyone who crawls our pages. We started using these values for our Algolia search configuration and internal reporting, but have since expanded to sharing this data with other teams that consume our content for AI systems too. + +Additionally, this decisions means that our GitHub repo is always the source of truth. We do not have to keep a spreadsheet or mapping updated elsewhere, the source of truth is always in our repo and - by extension - a lot more likely to be accurate than if we maintained multiple sources of truth. + +--- + +## How we ensure quality + +It's difficult to avoid errors with this kind of metadata, specifically because we are relying on freeform text entry in the frontmatter of individual files. + +We utilize [Zod schemas](https://zod.dev/) heavily in our Astro site, which are defined in [`src/schemas/`](https://github.com/cloudflare/cloudflare-docs/tree/production/src/schemas). + +These allow us to provide [Intellisense guidance](https://docs.astro.build/en/reference/experimental-flags/content-intellisense/) for contributors using IDEs for local development. + +![Intellisense in action](~/assets/images/style-guide/how-we-docs/intellisense.png) diff --git a/src/content/docs/style-guide/how-we-docs/redirects.mdx b/src/content/docs/style-guide/how-we-docs/redirects.mdx new file mode 100644 index 000000000000000..dd80bf8fc0137db --- /dev/null +++ b/src/content/docs/style-guide/how-we-docs/redirects.mdx @@ -0,0 +1,132 @@ +--- +pcx_content_type: how-to +title: Redirects +meta: + title: Redirects | How we docs +--- + +import { Details, GitHubCode, GlossaryTooltip } from "~/components"; + +As your content changes (and it will change), redirects preserve continuity for your users and (friendly) bots. + +The most obvious part of this is the user experience. If you click a link in the dashboard or use a bookmarked URL, you trust that it's taking you to the right place. Not a `404` page or the wrong page, but the right page. Redirects help direct users to the right place. + +The same applies to the automated experience. If you move a page without redirects, you are losing the historical search authority that Google and other search engines use to rank your page. + +--- + +## How we add redirects + +### Cloudflare Workers (primary) + +Our primary method takes advantage of [Workers Static Assets](/workers/static-assets/redirects/), defining redirects in a [plain text file](https://github.com/cloudflare/cloudflare-docs/blob/production/public/__redirects) in our GitHub repo. + +This setup allows us to use the same workflow for redirects as for any other documentation change. We implement a redirect in the same pull request as the content change and can test these changes in our preview branches. For maintenance, we try to keep these redirects [organized](#organize-your-redirects) by product and then — within each product — organized alphabetically. + +We also love the flexibility provided by the [Pages syntax](/workers/static-assets/redirects/#advanced-redirects). + +### Bulk redirects (secondary) + +In certain situations, we also use [Bulk redirects](/rules/url-forwarding/bulk-redirects/). We use this strategy sparing because having redirects in multiple places increases the cognitive load and potential confusion of making a change. + +Normally, bulk redirects only come up when another team is adding a large number of individual redirects to our site, such as when all of our previous `support.cloudflare.com` content was migrated and needed individualized redirects per locale. + +We use this method when the contributors are outside of our team and when the total number of redirects is so large that it would clutter our `__redirects` file and count against our [limit for redirects](/workers/static-assets/redirects/#surpass-_redirects-limits). + +--- + +## When we add redirects + +Our team adds redirects in two situations: during the course of normal content and as needed based on data. + +### During content work + +During normal content work, you want to add redirects when you do the following to a page: + +- Change any part of the URL (filename, folder). +- Delete the page. + +We have some automation to help [flag needed redirects](#potential-redirects). + +### Based on data + +Another time to add redirects is when you see a lot of `404` response codes on certain paths of your docs site. These `404` responses might be due to a missing redirect or mistyped link. + +We identify these status codes either through our [Cloudflare analytics](/analytics/account-and-zone-analytics/zone-analytics/) (ad hoc) or [Logpush job](/logs/about/) (more thorough, quarterly). + +--- + +## How we automate redirects + +We have two automations in GitHub to help with redirects. + +### Infinite redirects + +An infinite redirect is when two pages keep redirecting to each other, trapping users in an infitnite loop that will crash their browser. + +Because that's just a terrible experience, we explicitly check for that as part of our [required `CI` GitHub action](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/ci.yml#L62-L63). + +We trigger this check _after_ we build our site. What it does it then call [`validate-redirects.ts`](https://github.com/cloudflare/cloudflare-docs/blob/production/bin/validate-redirects.ts), which fails on: + +- Infinite redirects +- Duplicate redirects +- Redirect targets with anchor links in them + +
+ +
+ +### Potential redirects + +Contributors often struggle to know when they should add redirects. We try to help them by [adding a comment](https://github.com/cloudflare/cloudflare-docs/blob/production/.github/workflows/potential-redirects-or-partials.yml) to any pull requests that modify or delete content file paths. + +![GitHub Actions redirect comment](~/assets/images/style-guide/how-we-docs/redirects-github.png) + +--- + +## Other guidance + +### Organize your redirects + +As much as you can, try to organize your redirects into logical groups (products, alphabetical order). This process helps prevent duplicate redirects, as well as identifying specific ones you might be looking for. + +In our [`__redirects` file](https://github.com/cloudflare/cloudflare-docs/blob/production/public/__redirects), we use extensive comments, separating different product areas. We also try, as much as we can, to keep the redirects in alphabetical order within a section. + +We used to apply a similar principle to [Bulk Redirect lists](/rules/url-forwarding/bulk-redirects/) (when that was our primary method). We created lists that grouped together similar products and labeled them as such, so it was easier to find which redirect you were looking for. + +### Know what you can redirect + +At the server level, you can trigger a redirect on a URL path (`/page/`), but not a fragment (`/page/#fragment`). + +You can redirect a page to a fragment, however (`/page1/` to `/page2/#fragment`). + +### Avoid redirect chains + +If possible, have all redirects send your users directly to their destination instead of chaining together redirects. + +Otherwise, you can have the following situation: + +```txt +Page 1 --Redirect-> Page 2 --Redirect-> Page 3 --Redirect-> Page 4 +``` + +Redirect chains are bad because they: + +- Slow down the user experience. +- Increase the likelihood of unintentional outcomes (infinite redirects, missing redirects, incorrect redirects). + +A way to avoid this outcome is by continually updating the destinations of previous redirects. For example, let's say you changed the name of this page to `/style-guide/how-we-docs/redirect-guidance/`. + +In the pull request to update your redirects file, you would want to update the existing redirect as well as adding a new redirect: + +```diff title="__redirects" +- /style-guide/redirects/ /style-guide/how-we-docs/redirects/ 301 ++ /style-guide/redirects/ /style-guide/how-we-docs/redirect-guidance/ 301 ++ /style-guide/how-we-docs/redirects/ /style-guide/how-we-docs/redirect-guidance/ 301 +``` diff --git a/src/content/partials/style-guide/link-types.mdx b/src/content/partials/style-guide/link-types.mdx new file mode 100644 index 000000000000000..d740b09b624836a --- /dev/null +++ b/src/content/partials/style-guide/link-types.mdx @@ -0,0 +1,9 @@ +--- +{} +--- + +There are 3 types of links: + +- **External**: To other resources, such as www.cloudflare.com. +- **Internal**: To other pages in the docs, such as [Workers](/workers/). +- **Anchor**: To specific parts of other pages in our docs, such as [Proxied records](/dns/proxy-status/#proxied-records).