diff --git a/.agents/skills/contributing/SKILL.md b/.agents/skills/contributing/SKILL.md index a561ec84d02..7b161eb3083 100644 --- a/.agents/skills/contributing/SKILL.md +++ b/.agents/skills/contributing/SKILL.md @@ -9,6 +9,8 @@ This is the single skill to load for any change to the Cloudflare Docs repositor Do not guess at conventions. The references below are the source of truth for how this repo expects content to be written, structured, and validated. +Canonical references override conflicting local patterns, especially for product section names, folders, and ordering. + ## Ground rules These apply to every task below. diff --git a/.agents/skills/contributing/references/information-architecture.md b/.agents/skills/contributing/references/information-architecture.md index adf414a0ccd..4295191c532 100644 --- a/.agents/skills/contributing/references/information-architecture.md +++ b/.agents/skills/contributing/references/information-architecture.md @@ -12,21 +12,31 @@ Decide where a change lives before you write it. Putting content in the right pl | Changelog entry | `src/content/changelog/{product}/` | | Glossary terms | `src/content/glossary/{product}.yaml` | | Product metadata | `src/content/directory/{slug}.yaml` | -| Directory entry | `src/content/directory/{slug}.yaml` | Rules: - Filenames are lowercase with dashes: `get-started.mdx`, `create-api-token.mdx`. - Every folder must have an `index.mdx`. -- Only `.mdx`, `.md`, `.json`, `.yml`, `.yaml`, `.txt` are allowed under `src/content/`. Images must not go there. +- Only `.mdx`, `.json`, `.yml`, `.yaml`, `.txt` are allowed under `src/content/`. Images must not go there. + +## Follow the canonical product structure + +Use the [Information architecture](/style-guide/documentation-content-strategy/information-architecture/) page as the source of truth. Existing product structures do not override it. + +Every product requires: + +- An Overview at the product root `index.mdx`. +- A `get-started/` folder that takes a new user to a first working result. + +Product-specific and category-shared sections are additive. Their names must be clear and distinct from the core section names. They must not replace, rename, or reshape a core section. If the canonical structure does not fit, raise the issue through docs governance instead of changing the core locally. ## Find the right spot Before creating a file: -1. **Read the surrounding pages.** Open the product's `index.mdx` and 2–3 sibling pages. Match their structure, depth, and content type. +1. **Read the surrounding pages.** Open the product's `index.mdx` and 2–3 sibling pages. Match their voice, depth, and page-level conventions. Compare their folders and ordering against the canonical structure; do not copy outdated local information architecture. 2. **Check for existing coverage.** Search the docs (and use the `cloudflare-docs` search tool) for the topic. If a page already covers it, edit that page or link to it — do not create a near-duplicate. -3. **Place it in the navigation.** The left-nav order comes from `sidebar.order` in frontmatter (lower = higher). Slot the new page among its siblings by setting an order consistent with neighbors; use `sidebar.label` only when the title is too long for the nav. `hideChildren` (or `sidebar.group.hideIndex`) collapses a group to its index page. +3. **Place it in the navigation.** The left-nav order comes from `sidebar.order` in frontmatter (lower = higher). Slot the new page among its siblings by setting an order consistent with neighbors; use `sidebar.label` only when the title is too long for the nav. `hideChildren` collapses a page's children. `sidebar.group.hideIndex` hides the group's index page while retaining its children. ## Link to the source of truth @@ -58,6 +68,20 @@ pnpm exec tsm bin/validate-redirects.ts Adding redirects for renamed/moved files is also a documentation-checklist item on the PR (see the `pr` skill). +## Migrate an existing product + +Audit the product against the canonical structure, then: + +1. Confirm that the product has an Overview, Get started, and nonempty Platform section. +2. Rename nonstandard core folders to their standard names. +3. Convert loose core pages into folders with an `index.mdx`. +4. Move misplaced core content into the corresponding top-level core folder. +5. Add applicable missing core sections and order them canonically. +6. Keep product-specific sections only when they are uniquely named and additive. +7. Add redirects for every changed route and update affected internal links. +8. Update sidebar ordering and navigation metadata. +9. Run the standard content checks and redirect validation. + ## New product When documenting a product that does not exist in the repo yet: @@ -69,8 +93,11 @@ When documenting a product that does not exist in the repo yet: ``` 2. Create the docs folder with an `index.mdx` (`pcx_content_type: overview`). +3. Add a `get-started/` folder. +4. Add folders for the remaining applicable core sections in canonical order, including a nonempty `platform/` folder. +5. Add clearly named product-specific or category-shared sections only after the core sections. -Changelog entries require the changelog folder name to match a `directory` entry id (the folder name under `src/content/changelog/` must correspond to a file in `src/content/directory/`). +Changelog entries require the changelog folder name to match a directory entry's collection ID: the filename stem under `src/content/directory/`, not the six-character `id` field inside the YAML file. ## Glossary terms diff --git a/.agents/skills/contributing/references/writing-docs.md b/.agents/skills/contributing/references/writing-docs.md index 468b4d88cc3..c4e25d92765 100644 --- a/.agents/skills/contributing/references/writing-docs.md +++ b/.agents/skills/contributing/references/writing-docs.md @@ -2,7 +2,7 @@ The end-to-end process for adding or changing a documentation page. Work through these steps in order. Each step links to the reference that holds the detail. -You are an editor first. Match the existing voice, structure, and depth of the pages around the one you are changing. Keep edits small unless the task is a deliberate restructure. +You are an editor first. Match the existing voice and depth of the pages around the one you are changing, but follow the canonical information architecture instead of preserving outdated local structure. Keep edits small unless the task is a deliberate restructure. ## 1. Gather context @@ -10,7 +10,7 @@ Confirm you have enough to write something accurate before you write anything. I ## 2. Locate where the change belongs -Before creating a file, find where it fits. Read sibling pages in the same product area to learn the local patterns, and decide whether this is even a new page. +Before creating a file, read `information-architecture.md` and find where the change fits in the canonical product structure. Read sibling pages for context and page-level conventions, not as structural authority, and decide whether this is even a new page. Read `information-architecture.md` for: file locations, sidebar ordering, whether to extract a partial instead of a page, whether existing content already covers this (link to it rather than duplicate), and what to do when you rename or move a page (redirects). @@ -66,4 +66,4 @@ When the change is ready, load the `pr` skill to create the PR (drafts only, `[P ## Editing existing pages -When editing rather than creating: preserve the existing structure and voice, change only what the task requires, and do not rewrite surrounding content or "improve" unrelated phrasing. Read the whole file (and its neighbors) for context before touching a diff. +When editing rather than creating, preserve the page-level structure and voice, change only what the task requires, and do not rewrite surrounding content or "improve" unrelated phrasing. Do not preserve nonstandard section names, placement, or ordering when the task is a deliberate restructure. For focused edits, flag unrelated information architecture drift instead of expanding the scope. Read the whole file and its neighbors for context before touching a diff. diff --git a/src/content/docs/style-guide/documentation-content-strategy/information-architecture.mdx b/src/content/docs/style-guide/documentation-content-strategy/information-architecture.mdx index 551c1d3f59a..c5f347343f1 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/information-architecture.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/information-architecture.mdx @@ -25,27 +25,27 @@ Every product includes at least these two pages, from its first release: Beyond the required pair, use these standard sections whenever your product has the content they describe. Use the standard name so that readers and agents navigate every product's docs the same way. -| Section | What it contains | Related content type | -| --- | --- | --- | -| Overview | Orients a new reader to the product and routes them onward. Required. | [Overview](/style-guide/documentation-content-strategy/content-types/overview/) | -| Get started | The shortest path from nothing to a first working result. Required. | [Get started](/style-guide/documentation-content-strategy/content-types/get-started/) | -| Concepts | What the product's key ideas are and why they work the way they do. | [Concept](/style-guide/documentation-content-strategy/content-types/concept/) | -| Features | Groups the task and settings content for a major feature of the product. | [How to](/style-guide/documentation-content-strategy/content-types/how-to/) | -| Guides | Task-focused pages for completing one specific job. | [How to](/style-guide/documentation-content-strategy/content-types/how-to/) | -| Tutorials | End-to-end lessons where the reader builds a real project. | [Tutorial](/style-guide/documentation-content-strategy/content-types/tutorial/) | -| Examples | Complete, runnable samples that show how something is done. | None | -| Configuration | The settings, values, and options for a configuration-intensive feature. | [Configuration](/style-guide/documentation-content-strategy/content-types/configuration/) | -| Reference | Complete, neutral lookup details such as parameters, values, and options. | [Reference](/style-guide/documentation-content-strategy/content-types/reference/) | -| API | The product's API documentation and command guidance. | [API content strategy](/style-guide/api-content-strategy/) | -| Models | The available models and their details, for AI products. | [Reference](/style-guide/documentation-content-strategy/content-types/reference/) | -| Observability | Testing, metrics, analytics, and local development. | None | -| Best practices | Recommended patterns and guidance for using the product well. | None | -| Platform | Product-wide pages such as pricing, limits, changelog, betas, and known issues. | [Changelog](/style-guide/documentation-content-strategy/content-types/changelog/) | -| Glossary | The product's defined terms. | [Glossary](/style-guide/build-the-page/components/glossary/) | +| Section | What it contains | Related content type | +| -------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Overview | Orients a new reader to the product and routes them onward. Required. | [Overview](/style-guide/documentation-content-strategy/content-types/overview/) | +| Get started | The shortest path from nothing to a first working result. Required. | [Get started](/style-guide/documentation-content-strategy/content-types/get-started/) | +| Concepts | What the product's key ideas are and why they work the way they do. | [Concept](/style-guide/documentation-content-strategy/content-types/concept/) | +| Features | Groups the task and settings content for a major feature of the product. | [How to](/style-guide/documentation-content-strategy/content-types/how-to/) | +| Guides | Task-focused pages for completing one specific job. | [How to](/style-guide/documentation-content-strategy/content-types/how-to/) | +| Tutorials | End-to-end lessons where the reader builds a real project. | [Tutorial](/style-guide/documentation-content-strategy/content-types/tutorial/) | +| Examples | Complete, runnable samples that show how something is done. | None | +| Configuration | The settings, values, and options for a configuration-intensive feature. | [Configuration](/style-guide/documentation-content-strategy/content-types/configuration/) | +| Reference | Complete, neutral lookup details such as parameters, values, and options. | [Reference](/style-guide/documentation-content-strategy/content-types/reference/) | +| API | The product's API documentation and command guidance. | [API content strategy](/style-guide/api-content-strategy/) | +| Models | The available models and their details, for AI products. | [Reference](/style-guide/documentation-content-strategy/content-types/reference/) | +| Observability | Testing, metrics, analytics, and local development. | None | +| Best practices | Recommended patterns and guidance for using the product well. | None | +| Platform | Product-wide pages such as pricing, limits, changelog, betas, and known issues. | [Changelog](/style-guide/documentation-content-strategy/content-types/changelog/) | +| Glossary | The product's defined terms. | [Glossary](/style-guide/build-the-page/components/glossary/) | ## Structure and ordering rules -- Make each core section a folder, even when it currently holds a single page. A lone `get-started.mdx` becomes a `get-started/` folder. +- Keep the Overview at the product root `index.mdx`. Make every other core section a folder, even when it currently holds a single page. A lone `get-started.mdx` becomes a `get-started/` folder. - Place the core folders before any product-specific folders, in the order given under [Core sections](#core-sections). - Give every product a Platform folder that holds at least one page, so this section is present consistently rather than only on some products. - Name any product-specific folder uniquely and clearly. A product-specific folder is additive: it adds to the core, and it never replaces or reshapes a core section.