Style guide best practices

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/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
 

src/content/docs/style-guide/how-we-docs/image-maintenance.mdx

@@ -0,0 +1,65 @@
+---
+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
+
+Of these, we prefer Mermaid diagrams because they are searchable and 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.
+
+Additionally, you should only use screenshots intentionally, such as when there's a clear user confusion that needs a visual image. [Find account and zone ID](/fundamentals/account/find-account-and-zone-ids/) is a good illustration of this, because it's a common user pain point and one that's very difficult in the current Cloudflare UI.
+
+## 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 it 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. If there are unreferenced files, creates a [GitHub issue](https://github.com/cloudflare/cloudflare-docs/issues/23343) listing them out.
+
+### 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.
+
+<GitHubCode
+	repo="cloudflare/cloudflare-docs"
+	file="astro.config.ts"
+	commit="aaacc3c3c2a7517ee307ddfc56962cbea9847202"
+	lang="ts"
+	lines="62-76"
+	code={{ title: "astro.config.ts", mark: 5 }}
+/>
+
+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.
+
+<GitHubCode
+	repo="cloudflare/cloudflare-docs"
+	file="src/plugins/remark/validate-images.ts"
+	commit="fdeaadcfa99030d085512e721bc0a5948dcf70d4"
+	lang="ts"
+	code={{ title: "validate-images.ts" }}
+/>
+
+When paired with [flagging unused images](#flag-unused-images), this path validation ensures that a tech writer can safely delete unused files in a PR. So long as the site builds correctly, you have only deleted image files that are not referenced anywhere.

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.
+
+<DirectoryListing />

src/content/docs/style-guide/how-we-docs/links.mdx

@@ -0,0 +1,6 @@
+---
+pcx_content_type: how-to
+title: Links
+meta:
+  title: Links | How we docs
+---

src/content/docs/style-guide/how-we-docs/metadata.mdx

@@ -0,0 +1,6 @@
+---
+pcx_content_type: how-to
+title: Metadata
+meta:
+  title: Metadata | How we docs
+---

src/content/docs/style-guide/how-we-docs/redirects.mdx

@@ -0,0 +1,6 @@
+---
+pcx_content_type: how-to
+title: Redirects
+meta:
+  title: Redirects | How we docs
+---