structure for metadata page

Author: kodster28

public/__redirects

@@ -1317,6 +1317,8 @@
 /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
 

src/content/docs/docs-guide/manage-content/metadata/index.mdx

@@ -0,0 +1,104 @@
+---
+pcx_content_type: how-to
+title: Metadata
+meta:
+  title: Metadata | How we docs
+---
+
+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.
+
+{/* GitHubCode example of a product.yaml file */}
+
+### Page-level attributes
+
+We primarily set page-level attributes through the [page's frontmatter](/style-guide/frontmatter/custom-properties/).
+
+{/* GitHubCode example of a specific file with a lot of them */}
+
+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"
+<meta name="pcx_content_group" content="Core platform" >
+<meta name="pcx_product" content="AI Audit" >
+<meta name="pcx_content_type" content="get-started" >
+<meta name="pcx_last_modified" content="7" >
+```
+
+We render these values using a custom override for our [`Head.astro`]() file.
+
+{/* GitHubCode for Head.astro */}
+
+### 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 heavily in our Astro site, which are defined at [tbd](/tbd/).
+
+These allow us to provide Intellisense guidance for contributors using IDEs for local development.
+
+### Optional or required
+
+At the moment, most of our Zod schemas are purely optional, meaning that they will not cause a build to fail.
+
+However, we do have one value, `tags`, that we enforce an allowlist as part of our schema validation. We enforce this schema specifically because we render it as a customer-facing facet for our [search page](/search/), meaning that typos are more disruptive than for other types of metadata.
+
+To try and make this list a bit more flexible, we've included `alternate` values that can lead to the same presented value.