Style guide best practices

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

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.
 

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 / <br/> priority 1/] --> I{{Customer <br/> data ce
 E[Anycast IP] --> G[/Tunnel 2 / <br/> priority 1/] --> J{{Customer <br/> data center/ <br/> network 2}}
 E[Anycast IP] --> H[/Tunnel 3 / <br/> priority 2/] --> K{{Customer <br/> data center/ <br/> network 3}}
 ```
-````
+````
+
+## Related components
+
+- [Diagrams](/style-guide/documentation-content-strategy/component-attributes/diagrams/)
+- [Screenshots](/style-guide/documentation-content-strategy/component-attributes/screenshots/)

src/content/docs/style-guide/documentation-content-strategy/component-attributes/diagrams.mdx

@@ -1,7 +1,6 @@
 ---
 pcx_content_type: concept
 title: Diagrams
-
 ---
 
 ## Definition
@@ -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,8 @@ 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.
+
+## Related components
+
+- [Mermaid diagrams](/style-guide/components/mermaid/)
+- [Screenshots](/style-guide/documentation-content-strategy/component-attributes/screenshots/)

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.
+<Render file="link-types" />
 
 ## 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/<ACCOUNTID>/rulesets`" and add text to say "replace `<ACCOUNTID>` 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/<ACCOUNTID>/rulesets`" and add text to say "replace `<ACCOUNTID>` 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/).