DOCS-3147: Add contributor content types and page templates

AGENTS.md

@@ -0,0 +1,38 @@
+# Agent instructions
+
+This file is for AI coding agents working in this repository.
+For the build, the product directories, and other repository conventions, read [.github/copilot-instructions.md](.github/copilot-instructions.md).
+
+## Writing a new page
+
+Follow this section only when you create a new documentation page: a new `.md` or `.mdx` file under `calico/`, `calico-enterprise/`, `calico-cloud/`, or `use-cases/`.
+
+It doesn't apply when you:
+
+- Edit, correct, or add to an existing page.
+- Copy an existing page to another product or version.
+- Move or rename a page.
+- Create a partial, such as a file whose name starts with `_`.
+
+In those cases, keep the page's existing title, headings, and structure.
+Don't restructure an existing page to fit a content type unless the person asks you to.
+
+### Choose a content type
+
+Every new page has one content type, chosen for what the reader is trying to do.
+Read [content-types.md](contributors/content-types/content-types.md) and choose a type: how-to, explanation, tutorial, reference, installation guide, or troubleshooting.
+If the request covers more than one type, such as steps plus a long explanation of how a feature works, suggest separate pages and ask before you write them.
+If you can't tell which type fits, ask.
+
+### Start from the template
+
+Copy the template for that type from [contributors/content-types/templates/](contributors/content-types/templates/), and fill it in.
+
+- Keep every section marked REQUIRED.
+  Include RECOMMENDED sections unless there's nothing to say, and OPTIONAL sections only when they help the reader.
+- Follow the guidance in each comment, then delete the comment.
+  You can keep the user story comment.
+- Keep the `content_type` value that the template sets in the front matter.
+- Check the page against the reviewer checklist at the end of the template, then delete the checklist.
+
+When you finish, tell the person which content type you used and why.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

contributors/README.md

@@ -0,0 +1,7 @@
+# Contributor guide
+
+Guidance for writing and maintaining Calico documentation.
+
+* [Content types](content-types/content-types.md)
+* [Style guide](style-guide.md)
+* [Templates](content-types/templates/)

contributors/content-types/content-types.md

@@ -0,0 +1,71 @@
+# Content types
+
+Every page in the Calico documentation has one content type.
+Pick the type that matches what the reader is trying to do.
+
+## About content types
+
+Readers come to the docs to do something specific.
+They might want to learn, finish a task, look something up, or understand how something works.
+Each content type serves one of these needs.
+A page that tries to serve several needs at once doesn't serve any of them well.
+A tutorial that stops to explain design history loses the learner.
+A reference page that turns into a procedure is hard to scan.
+
+Start every page from the reader's purpose, not from what we built.
+A page that exists to show off a feature broadcasts at the reader.
+It doesn't help them.
+Before you write, ask who's reading the page and what they need to do or know when they finish.
+The answer tells you the content type.
+
+Our content types are based on [Diátaxis](https://diataxis.fr/).
+Diátaxis is a framework that sorts documentation into four types, one for each kind of reader need.
+We use those four as our core content types.
+We also have specialized types that build on the core types for situations that come up often in our docs.
+
+## Content types
+
+### Core content types
+
+| Content type | Reader's need | Question it answers |
+|---|---|---|
+| Tutorial | Learning | Can you teach me to...? |
+| How-to guide | Doing a task | How do I...? |
+| Reference | Looking up facts | What is...? |
+| Explanation | Understanding | Why...? |
+
+**Tutorial.** A tutorial teaches a new user by walking them through a complete, working example.
+The reader is studying, not doing their own work.
+The tutorial is responsible for the reader's success, so every step must work as written.
+Keep explanation to a minimum and link out to it.
+See [Tutorials](https://diataxis.fr/tutorials/).
+
+**How-to guide.** A how-to guide gives a competent user the steps to finish a specific, real-world task.
+It assumes the reader already knows what they want to do.
+Don't teach in a how-to, and don't go off on tangents.
+See [How-to guides](https://diataxis.fr/how-to-guides/).
+
+**Reference.** A reference page describes the product as it is: resources, fields, flags, APIs, and values.
+Readers consult it rather than read it from start to finish.
+It follows the structure of the product and must be accurate and complete.
+It describes; it doesn't instruct or explain.
+See [Reference](https://diataxis.fr/reference/).
+
+**Explanation.** An explanation page helps the reader understand a topic: how it works, why it's designed that way, and what the trade-offs and alternatives are.
+Readers usually read it away from the keyboard.
+See [Explanation](https://diataxis.fr/explanation/).
+
+### Specialized content types
+
+**Installation guide.** An installation guide is a how-to guide for installing a product on a specific platform.
+It's a separate type because installation is the first task most readers do.
+It depends on platform, version, and prerequisites, and it ends with a check that the install worked.
+
+**Troubleshooting.** A troubleshooting page is a how-to guide that starts from a symptom rather than a goal.
+The reader has a problem, and the page helps them find the cause and fix it.
+Each symptom can have more than one cause, and each cause has its own fix.
+When problems happen only while the reader follows one procedure, cover them in a Troubleshooting section of that how-to guide instead.
+
+**Release notes.** Release notes are a sub-type of reference, scoped to a single release.
+The reader wants to know what changed and whether it affects them: new features, fixed bugs, known issues, and anything they must do before or after they upgrade.
+Lead with changes that need the reader to act, such as breaking changes and deprecations.

contributors/content-types/templates/explanation.mdx

@@ -0,0 +1,135 @@
+---
+description: "[What the reader will understand after reading this page, in one sentence of 130 to 160 characters. Use the full product name.]"
+content_type: explanation
+---
+
+{/*
+  EXPLANATION TEMPLATE
+
+  Copy this file to a new .mdx file to start an explanation page.
+  Replace the text in square brackets.
+  Delete the guidance comments, including this one, before you open a pull request.
+
+  An explanation page helps the reader understand a topic: what it is, how it works, and why it works that way.
+  Readers come here before a task, when they're deciding whether a feature fits their needs, or when a how-to sends them to a concept they don't know yet.
+
+  An explanation page has no procedures and no reference tables.
+  Link to how-to guides and reference pages instead.
+
+  Good examples in our docs:
+  - calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx
+  - calico/networking/ingress-gateway/about-calico-ingress-gateway.mdx
+  - calico/operations/ebpf/use-cases-ebpf.mdx
+
+  Read content-types.md for how explanation fits with the other content types.
+*/}
+
+{/*
+  OPTIONAL: User story
+
+  Record who the page is for and what they need from it.
+  This comment can stay on the page.
+
+  As a [role], I want to understand [topic] so that I can [decision or task].
+*/}
+
+# About [topic]
+
+{/*
+  REQUIRED: Title
+
+  Use "About [topic]" or a short noun phrase that names the topic.
+  Don't start with a verb, because a verb signals a how-to guide.
+*/}
+
+[One or two sentences that say what the topic is.]
+[One sentence that says what this page covers, so readers can tell whether it answers their question.]
+
+{/*
+  REQUIRED: Lead paragraph
+
+  Put the most important information first.
+  A reader who stops after this paragraph should still know what the topic is.
+  If it helps, say what the page doesn't cover and link to where that is.
+*/}
+
+## Why [topic]
+
+{/*
+  RECOMMENDED: The reader's problem
+
+  Start from the problem the reader has, not from the feature.
+  Describe what the reader would have to do without it.
+  Don't sell. Say what the feature does for the reader, not how impressive it is.
+*/}
+
+## How [topic] works
+
+{/*
+  RECOMMENDED: The mechanism
+
+  Describe the parts and how they relate.
+  Define each term the first time you use it.
+  If one diagram makes this clearer, put it here.
+*/}
+
+## [A question the reader has]
+
+{/*
+  REQUIRED: Topic sections
+
+  Add one section for each question the reader has about the topic.
+  Phrase each heading the way the reader would ask it.
+  For example, "Which bridge mode do you need" or "Where policy is enforced".
+  Explain why, not only what: design decisions, constraints, and trade-offs belong here.
+  If you start explaining a second topic, give it its own page and link to it.
+*/}
+
+## When to use [topic]
+
+{/*
+  RECOMMENDED: Trade-offs and alternatives
+
+  Say when the feature is the right choice and when it isn't.
+  Include limitations.
+  If there are alternatives, compare them in a table.
+
+  | Option | Use it when | Trade-off |
+  |---|---|---|
+  | [Option A] | [Situation] | [Cost or limitation] |
+  | [Option B] | [Situation] | [Cost or limitation] |
+*/}
+
+## Next steps
+
+{/*
+  OPTIONAL: Next steps
+
+  Link to the one or two pages a reader is most likely to need next, usually a how-to guide or tutorial.
+*/}
+
+- [Link to a how-to guide or tutorial]
+
+## Additional resources
+
+{/*
+  RECOMMENDED: Additional resources
+
+  Link to related how-to guides, reference pages, and other explanation pages.
+  Keep the list short.
+*/}
+
+- [Link to a how-to guide]
+- [Link to a reference page]
+
+{/*
+  REVIEWER CHECKLIST
+
+  - The page explains one topic.
+  - The title is "About [topic]" or a noun phrase, not a verb.
+  - The lead paragraph says what the topic is and what the page covers.
+  - The page starts from the reader's problem, not from the feature.
+  - The page explains why, not only what.
+  - The page has no steps and no reference tables.
+  - Related how-to guides and reference pages are linked.
+*/}