From e97ccbeb059267fd58a26c627df17df7328a3a41 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Wed, 4 Nov 2026 12:59:02 +0000 Subject: [PATCH 1/3] DOCS-3147: Add contributor content types and page templates Add a contributor guide that explains content types and gives a template for each one. Content types are based on Diataxis, with installation guides, troubleshooting, and release notes as specialized types. --- contributors/README.md | 7 + contributors/content-types/content-types.md | 71 +++++++ .../content-types/templates/explanation.mdx | 134 ++++++++++++ .../content-types/templates/how-to.mdx | 192 ++++++++++++++++++ .../templates/installation-guide.mdx | 176 ++++++++++++++++ .../content-types/templates/reference.mdx | 138 +++++++++++++ .../templates/troubleshooting.mdx | 152 ++++++++++++++ .../content-types/templates/tutorial.mdx | 166 +++++++++++++++ contributors/style-guide.md | 5 + 9 files changed, 1041 insertions(+) create mode 100644 contributors/README.md create mode 100644 contributors/content-types/content-types.md create mode 100644 contributors/content-types/templates/explanation.mdx create mode 100644 contributors/content-types/templates/how-to.mdx create mode 100644 contributors/content-types/templates/installation-guide.mdx create mode 100644 contributors/content-types/templates/reference.mdx create mode 100644 contributors/content-types/templates/troubleshooting.mdx create mode 100644 contributors/content-types/templates/tutorial.mdx create mode 100644 contributors/style-guide.md diff --git a/contributors/README.md b/contributors/README.md new file mode 100644 index 0000000000..79c4fa9149 --- /dev/null +++ b/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/) diff --git a/contributors/content-types/content-types.md b/contributors/content-types/content-types.md new file mode 100644 index 0000000000..3a848933dc --- /dev/null +++ b/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. diff --git a/contributors/content-types/templates/explanation.mdx b/contributors/content-types/templates/explanation.mdx new file mode 100644 index 0000000000..5a4997e603 --- /dev/null +++ b/contributors/content-types/templates/explanation.mdx @@ -0,0 +1,134 @@ +--- +description: [What the reader will understand after reading this page, in one sentence of 130 to 160 characters. Use the full product name.] +--- + +{/* + 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. +*/} diff --git a/contributors/content-types/templates/how-to.mdx b/contributors/content-types/templates/how-to.mdx new file mode 100644 index 0000000000..6a0c6bc713 --- /dev/null +++ b/contributors/content-types/templates/how-to.mdx @@ -0,0 +1,192 @@ +--- +description: [What the reader will get done by following this page, in one sentence of 130 to 160 characters. Use the full product name.] +--- + +{/* + HOW-TO TEMPLATE + + Copy this file to a new .mdx file to start a how-to guide. + Replace the text in square brackets. + Delete the guidance comments, including this one, before you open a pull request. + + A how-to guide gives a competent reader the steps to finish one specific, real-world task. + The reader already knows what they want to do. + They need the steps, in order, and a way to tell that it worked. + + A how-to guide doesn't teach. + If the reader needs a concept explained, link to an explanation page. + If the reader needs a full list of fields or flags, link to a reference page. + + Good examples in our docs: + - calico-enterprise/networking/l2-bridge/connect-vlan.mdx + - calico/network-policy/policy-rules/log-rules.mdx + - calico/operations/istio/deploy-istio-ambient.mdx + + Read content-types.md for how the how-to guide 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 [task] so that [outcome]. +*/} + +# [Verb] [object] + +{/* + REQUIRED: Title + + Start with an imperative verb and name the task. + For example, "Connect workloads to an existing VLAN" or "Configure BGP peering". + Use the words the reader would search for. +*/} + +[One or two sentences that say what the reader will get done and why they'd want to.] +[If it helps, one sentence that says when to use this guide and when to use a different one.] + +{/* + REQUIRED: Lead paragraph + + Say what the task achieves, from the reader's point of view. + If a similar guide covers a different case, say which case this one covers and link to the other. + Keep background to a sentence or two, and link to an explanation page for more. +*/} + +## Before you begin + +{/* + REQUIRED, when there are prerequisites + + List what the reader must have in place before step 1: versions, licenses, permissions, installed components, and network setup. + Leave out the obvious, such as "a running Kubernetes cluster" or "kubectl installed". + Say what fails if a prerequisite is missing, when that isn't obvious. + Use the heading "Before you begin", not "Prerequisites". +*/} + +- [Prerequisite] +- [Prerequisite] + +## Limitations + +{/* + OPTIONAL: Limitations + + List what the task doesn't support or can't do, when the reader needs to know before starting. + For example, unsupported platforms, data planes, or configurations. + Keep each item to a sentence, and link to a reference page for the full list. +*/} + +- [Limitation] + +## [Verb] [object] + +{/* + REQUIRED: Steps + + Use one section for each stage of the task, and start each heading with a verb. + A short task can have a single section. + + Number the steps if there are two or more steps. + If there is only one step, use an unordered list. + Write each step as an instruction, and keep to one action per step. + When a step applies only in some cases, put the condition first, so readers can skip steps that don't apply. + For example, "If the value isn't Multus, set it" or "On each node, check the bridge". + Put commands and manifests in code blocks, and show expected output where it helps the reader confirm the step worked. + Keep explanation to what the reader needs to make the step's choice. + + If a task needs more than about ten steps, split it into stages, or consider whether it's a tutorial. +*/} + +1. [Step] + + ```bash + [command] + ``` + +2. [Step] + +## Verify + +{/* + REQUIRED: Verification + + Use "Verify" or "Verify [object]" as the heading, for example "Verify the installation". + Tell the reader how to confirm that the task worked, and what they should see. + Order the checks so that a failure tells the reader where to look. + Link to the Troubleshooting section or a troubleshooting page for what to do if a check fails. + For a short task, a final step in the procedure can do this job instead of a separate section. +*/} + +1. [Check] + + ```bash + [command] + ``` + + [Expected result.] + +## Troubleshooting + +{/* + OPTIONAL: Troubleshooting + + Cover only problems that happen while the reader follows this procedure. + Problems that can happen at any time, or that affect the feature more widely, belong on a troubleshooting page. + Link to that page instead. + Include a symptom only if it could affect many readers. + If it happens only under a narrow set of conditions, consider a support article instead. + + Use one subsection for each symptom, headed by the symptom in the reader's words or the exact error text. + Describe the symptom first, then give each cause with its fix, most common cause first. + Use the same labels as a troubleshooting page. +*/} + +### [Symptom as the reader sees it] + +[What the reader sees.] + +**Cause:** [Why it happens.] + +**Fix:** + +1. [Step to fix it] + +## Next steps + +{/* + OPTIONAL: Next steps + + Link to the one or two tasks a reader is most likely to do next. +*/} + +- [Link to the next how-to guide] + +## Additional resources + +{/* + RECOMMENDED: Additional resources + + Link to the explanation page for the topic, the reference pages for the resources used, and any troubleshooting page. + Keep the list short. +*/} + +- [Link to an explanation page] +- [Link to a reference page] + +{/* + REVIEWER CHECKLIST + + - The page covers one task. + - The title starts with an imperative verb. + - The lead paragraph says what the reader will get done. + - Before you begin lists only the prerequisites that aren't obvious. + - Limitations, if any, are in their own section before the steps. + - A Troubleshooting section, if any, covers only problems that happen during this procedure. + - Every step is an instruction that does one thing, with any condition stated first. + - The page tells the reader how to confirm the task worked. + - Concepts are linked, not explained at length. + - Someone has followed the steps from start to finish. +*/} diff --git a/contributors/content-types/templates/installation-guide.mdx b/contributors/content-types/templates/installation-guide.mdx new file mode 100644 index 0000000000..98de828b7b --- /dev/null +++ b/contributors/content-types/templates/installation-guide.mdx @@ -0,0 +1,176 @@ +--- +description: [What the reader will install and on which platform, in one sentence of 130 to 160 characters. Use the full product name.] +--- + +{/* + INSTALLATION GUIDE TEMPLATE + + Copy this file to a new .mdx file to start an installation guide. + Replace the text in square brackets. + Delete the guidance comments, including this one, before you open a pull request. + + An installation guide is a how-to guide for installing a product on one platform or with one install method. + It's often the first task a reader does with the product, so it has to work the first time. + The reader is installing into their own environment, and they need to know what to prepare, what to run, and how to tell that it worked. + + An installation guide doesn't explain the product or compare platforms. + Link to explanation pages and to the system requirements instead. + + Good examples in our docs: + - calico-enterprise/getting-started/install-on-clusters/nkp.mdx + - calico-enterprise/installation/install-calico-enterprise-mke-4k.mdx + - calico-cloud/get-started/install-cluster.mdx + + Read content-types.md for how the installation guide 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 install $[prodname] on [platform] so that [outcome]. +*/} + +# Install $[prodname] on [platform] + +{/* + REQUIRED: Title + + Use "Install $[prodname] on [platform]". + Put the platform name on its own in sidebar_label, so the sidebar lists platforms. +*/} + +[One or two sentences that say what the reader will install and on which platform.] +[One sentence about anything that makes this platform different, such as a CNI plugin that must be removed or a setting that can't be changed later.] + +{/* + REQUIRED: Lead paragraph + + Say what the reader will end up with. + If something about this platform changes the usual install, say what it is and why it matters, in a sentence or two. + If the platform vendor certifies or supports the install, say so. +*/} + +## Before you begin + +{/* + REQUIRED: Before you begin + + List what the reader must have in place before step 1: + - Supported versions of the platform, linked to the compatibility page. + - Infrastructure that meets the system requirements, linked to the requirements page. + - Credentials, license keys, and registry access. + - Tools on the reader's workstation, and the access they need. + Say what fails if a prerequisite is missing, when that isn't obvious. +*/} + +- [Prerequisite] +- [Prerequisite] + +## Limitations + +{/* + OPTIONAL: Limitations + + List what this install doesn't support on this platform, when the reader needs to know before starting. + Keep each item to a sentence, and link to a reference page for the full list. +*/} + +## [Prepare the cluster] + +{/* + OPTIONAL: Platform preparation + + Use this section when the reader must do something on the platform before installing, such as creating a cluster without a CNI plugin. + Start the heading with a verb that names the task. + End with a check that the cluster is in the state the install expects. +*/} + +1. [Step] + +## Install $[prodname] + +{/* + REQUIRED: Install + + Give the install steps in order, with each command in a code block. + Write each step as an instruction, with any condition first. + Where the reader must wait, give the command to watch progress and say what to wait for. + When the reader has a choice, such as an existing component they can reuse, put the condition first and say what to skip. + + If the product can be installed in more than one way on this platform, such as with Helm or with manifests, use one section for each method, with the method in the heading. +*/} + +1. [Step] + + ```bash + [command] + ``` + +2. [Step] + +## Verify the installation + +{/* + REQUIRED: Verification + + Use "Verify the installation" as the heading. + Tell the reader how to confirm that the install worked, and what they should see at each check. + Start with the clearest signal, such as all nodes becoming ready. + Include a check that traffic flows, because running pods don't prove that the network works. + Say which results are expected for a while, such as components that report degraded while they start. + If a check can show that the wrong product or version was installed, say what that result means. +*/} + +1. [Check] + + ```bash + [command] + ``` + + [Expected result.] + +## Troubleshooting + +{/* + OPTIONAL: Troubleshooting + + Cover only problems that happen while the reader follows this install. + Include a symptom only if it could affect many readers. + Use one subsection for each symptom, then give each cause with its fix. +*/} + +### [Symptom as the reader sees it] + +[What the reader sees.] + +**Cause:** [Why it happens.] + +**Fix:** + +1. [Step to fix it] + +## Next steps + +{/* + RECOMMENDED: Next steps + + Link to the few tasks most readers do right after installing. + Keep the list short. +*/} + +- [Link to a how-to guide] + +{/* + REVIEWER CHECKLIST + + - The title is "Install $[prodname] on [platform]", and sidebar_label is the platform name. + - The lead paragraph says what the reader will install, and what's different about this platform. + - Before you begin links to the compatibility and system requirements pages. + - Every step is an instruction, with any condition first. + - Wherever the reader waits, the page says what to wait for. + - The page has a Verify the installation section, including a check that traffic flows. + - Someone has followed the install from start to finish on the platform. +*/} diff --git a/contributors/content-types/templates/reference.mdx b/contributors/content-types/templates/reference.mdx new file mode 100644 index 0000000000..c51b065ace --- /dev/null +++ b/contributors/content-types/templates/reference.mdx @@ -0,0 +1,138 @@ +--- +description: [What the reader can look up on this page, in one sentence of 130 to 160 characters. Use the full product name.] +--- + +{/* + REFERENCE TEMPLATE + + Copy this file to a new .mdx file to start a reference page. + Replace the text in square brackets. + Delete the guidance comments, including this one, before you open a pull request. + + A reference page describes the product as it is. + It can list resources and their fields, configuration options, environment variables, command flags, metrics, ports, or what a feature supports. + Readers don't read a reference page from start to finish. + They come to look up one fact, and they leave once they've found it. + A reference page must be accurate, complete, and easy to scan. + + A reference page describes. + It doesn't tell the reader what to do, and it doesn't explain why. + Link to how-to guides for tasks and to explanation pages for concepts. + + Resource pages, such as those in reference/resources/, follow their own conventions. + When you write one, follow its sibling pages. + + Don't hand-write a page that is generated from source, such as the CRD API reference. + + Good examples in our docs: + - calico/reference/resources/ippool.mdx, a resource + - calico/reference/configure-calico-node.mdx, configuration options + - calico-enterprise/reference/l2-bridge-support.mdx, what a feature supports + + Read content-types.md for how reference 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 look up [information] so that I can [decision or task]. +*/} + +# [Name of what the page describes] + +{/* + REQUIRED: Title + + Name what the page describes, using the name the reader sees in the product. + For example, "IP pool", "Configuring calico/node", or "L2 bridge support and limitations". + Don't use a generic title such as "Reference". +*/} + +[One or two sentences that say what the page describes and where it applies.] +[One sentence that says what the reader will find on the page, or when to read it.] + +{/* + REQUIRED: Lead paragraph + + Say what the thing is, in a sentence, and link to the explanation page for more. + Say what the reader will find on the page. + If the page applies only to some products, platforms, or install methods, say so here. +*/} + +## [Example] + +{/* + OPTIONAL: Example + + When the shape of the thing isn't obvious, show a short, valid example. + For a resource, this is a sample manifest. + For a command, this is a typical invocation. + Include what readers set most often, not everything. + Readers copy examples, so make sure this one works. +*/} + +```yaml +[example] +``` + +## [Reference section] + +{/* + REQUIRED: Reference sections + + This is the body of the page. + Organize it the way the product is organized, so readers can find an entry by where it appears in the product. + For example, group fields by the object they belong to, environment variables by the component that reads them, or support details by area. + Give each section a heading that names what it lists. + + Use a table when entries share the same attributes, and a list when they don't. + Use the same columns on every table on the page, and match sibling pages when they exist. + Common columns are a name, a description, accepted values, the type, and the default. + + In each entry, say what it is or does, not how to use it. + Give every default, or say that there isn't one. + Use names exactly as they appear in the product. + If a section needs a sentence of context, keep it to a sentence. +*/} + +| [Name] | Description | Default | +|---|---|---| +| [entry] | [What it is or does.] | [default] | + +## [Topic that needs more than a table cell] + +{/* + OPTIONAL: Detail sections + + Use a section when an entry or behavior needs more than a sentence or two, such as how selectors match or how validation works. + Keep it factual. + If the section turns into an explanation of why, move it to an explanation page and link to it. +*/} + +## Additional resources + +{/* + RECOMMENDED: Additional resources + + Link to the how-to guides that use what the page describes and to the explanation page for the topic. + Keep the list short. +*/} + +- [Link to a how-to guide] +- [Link to an explanation page] + +{/* + REVIEWER CHECKLIST + + - The title names what the page describes. + - The lead paragraph says what the page describes and what it lists. + - The page is organized the way the product is. + - Every entry is listed, with its default where one applies. + - Tables on the page use the same columns. + - Any example is valid and works if the reader copies it. + - The page has no steps and no long explanation. + - The page isn't a hand-written copy of generated content. +*/} diff --git a/contributors/content-types/templates/troubleshooting.mdx b/contributors/content-types/templates/troubleshooting.mdx new file mode 100644 index 0000000000..24818b7501 --- /dev/null +++ b/contributors/content-types/templates/troubleshooting.mdx @@ -0,0 +1,152 @@ +--- +description: [The problems this page helps the reader fix, in one sentence of 130 to 160 characters. Use the full product name.] +--- + +{/* + TROUBLESHOOTING TEMPLATE + + Copy this file to a new .mdx file to start a troubleshooting page. + Replace the text in square brackets. + Delete the guidance comments, including this one, before you open a pull request. + + A troubleshooting page is a how-to guide that starts from a symptom rather than a goal. + The reader has a problem, often under pressure. + They want to recognize their symptom, find the cause, and fix it, as fast as possible. + + A troubleshooting page covers one or more symptoms for one feature or area, such as egress gateways or BGP. + Each symptom has one or more causes, and each cause has a fix. + + If the problems happen only while the reader follows one procedure, don't write a troubleshooting page. + Add a Troubleshooting section to that how-to guide instead. + + Include a symptom only if it could affect many readers. + If it happens only under a narrow set of conditions, such as one version on one platform with a particular combination of dependencies, leave it out of the docs. + Consider a support article instead. + + A troubleshooting page doesn't teach a feature or explain how it works. + Link to explanation pages and how-to guides instead. + + Good examples in our docs: + - calico-enterprise/networking/l2-bridge/troubleshoot.mdx + - calico-enterprise/networking/egress/troubleshoot.mdx + - calico-cloud/threat/gateway-waf/troubleshooting.mdx + + Read content-types.md for how troubleshooting 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 find out why [problem] so that I can fix it without opening a support case. +*/} + +# Troubleshoot [feature or area] + +{/* + REQUIRED: Title + + Use "Troubleshoot [feature or area]". + If the page covers only one symptom, you can describe the symptom instead. + Don't use a generic title such as "Troubleshooting". +*/} + +[One or two sentences that say which feature or area the page covers.] +[If it helps, one sentence that tells the reader where to start.] + +{/* + REQUIRED: Lead paragraph + + Say what the page covers, so readers can tell whether their problem is here. + If the reader should read one section before looking for their symptom, say so. +*/} + +## Where to look + +{/* + OPTIONAL: Where to look + + Tell the reader where this feature reports problems: which logs, events, statuses, or metrics. + Include this section when the signals are somewhere the reader wouldn't expect. + Show the commands to read them. +*/} + +## Collect diagnostic information + +{/* + OPTIONAL: Diagnostic information + + List what to collect before the reader opens a support case, and how to collect it. + Say what the standard diagnostics bundle doesn't collect. + If the reader raises a log level, tell them to set it back afterwards. +*/} + +## [Symptom as the reader sees it] + +{/* + REQUIRED: One section for each symptom + + Write the heading as the symptom, in the reader's words. + For example, "The workload has no IP address" or "Pods can't reach the API server". + When the symptom is an error message or status, use its exact text as the heading, in code format. + Readers search for it, and a heading gives them a link to share. + + Start with what the reader sees, including exact error text and where it appears. + Then give each cause, followed by its fix, using the Cause and Fix labels. + When a symptom has more than one cause, repeat the pair for each one, most common cause first. + If the reader needs to check something to tell the causes apart, put that check in the cause. + + Keep each cause to a sentence or two. + Write each fix as numbered steps, and say how to confirm the problem is fixed if that isn't obvious. + + Order the symptom sections from the most common to the least. + Don't use Problem and Solution as headings, because they hide the symptom from readers who scan and search. +*/} + +[What the reader sees.] + +**Cause:** [Why it happens, and how to tell if this is the cause.] + +**Fix:** + +1. [Step to fix it] + + ```bash + [command] + ``` + +2. [Step] + +**Cause:** [A second cause, if there is one.] + +**Fix:** + +1. [Step to fix it] + +## Additional resources + +{/* + RECOMMENDED: Additional resources + + Link to the explanation page for the feature, the how-to guides that set it up, and the reference pages for the resources involved. + Keep the list short. +*/} + +- [Link to an explanation page] +- [Link to a how-to guide] + +{/* + REVIEWER CHECKLIST + + - The title names the feature or area, not just "Troubleshooting". + - The page covers problems that can happen at any time, not only during one procedure. + - Every symptom could affect many readers, not only those with one narrow combination of version, platform, and dependencies. + - Each symptom has its own section, headed by the symptom or the exact error text. + - Each section describes the symptom first, then each cause with its fix. + - Causes and fixes use the Cause and Fix labels. + - When a symptom has several causes, the most common comes first. + - Fixes are numbered steps. + - The page doesn't teach the feature or explain how it works at length. +*/} diff --git a/contributors/content-types/templates/tutorial.mdx b/contributors/content-types/templates/tutorial.mdx new file mode 100644 index 0000000000..413eb0fcf6 --- /dev/null +++ b/contributors/content-types/templates/tutorial.mdx @@ -0,0 +1,166 @@ +--- +description: [What the reader will build or learn by following this tutorial, in one sentence of 130 to 160 characters. Use the full product name.] +--- + +{/* + TUTORIAL TEMPLATE + + Copy this file to a new .mdx file to start a tutorial. + Replace the text in square brackets. + Delete the guidance comments, including this one, before you open a pull request. + + A tutorial teaches a reader who is new to a feature by walking them through a complete, working example. + The reader is learning, not doing their own work. + They follow your steps exactly, in an environment you choose, and they finish with something that works. + + The tutorial is responsible for the reader's success. + Every step must work as written, and the reader must be able to tell after each stage that they're on track. + + Keep explanation short. + A sentence on why a step matters helps the reader learn. + A long explanation belongs on an explanation page, so link to it. + + If the reader already knows what they want to do and needs the steps for their own environment, write a how-to guide instead. + + A tutorial is always its own page. + Don't put a tutorial inside another content type. + + Good examples in our docs: + - calico/getting-started/kubernetes/quickstart.mdx + - calico/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx + + Read content-types.md for how the tutorial 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] who is new to [feature], I want to [build or try something] so that I can [learn what]. +*/} + +# [Verb] [object] + +{/* + REQUIRED: Title + + Say what the reader will build or do in the tutorial. + For example, "Launch a canary deployment with Calico Ingress Gateway" or "Secure a cluster with network policy on kind". + Don't add a "Tutorial:" prefix, and don't use a generic title such as "Tutorial". +*/} + +In this tutorial, you [build or do what], and learn how to [learning objective]. +[One sentence that says what the reader will be able to do afterwards.] +[If it helps, one sentence that says how long the tutorial takes.] + +{/* + REQUIRED: Lead paragraph + + Use the word "tutorial" in the first sentence, so readers know this is a guided example and not a procedure for their own environment. + State what the reader will learn, not only what they'll build. + Say who the tutorial is for, if that isn't obvious. +*/} + +## Before you begin + +{/* + REQUIRED: Before you begin + + List everything the reader needs before step 1: tools, accounts, access, and what they should already know. + Link to installation instructions for each tool. + Prefer a disposable environment the reader creates in the tutorial, such as a kind cluster, so the steps work the same for everyone and nothing in the reader's own clusters is at risk. +*/} + +- [Tool, with a link to how to install it] +- [Tool, with a link to how to install it] + +## Step 1: [Verb] [object] + +{/* + REQUIRED: Steps + + Use one section for each stage of the tutorial. + Number the sections in the heading, in the format "Step 1: [Verb] [object]". + Each stage builds on the one before. + + Optionally, start each section with a sentence that says what the reader will do in it. + Number the steps when there are two or more. + Write each step as an instruction, with any condition first. + Give every name, value, and file content the reader needs, so that they never have to make a choice. + + End each section with a checkpoint. + Show the command the reader runs and the output they should see, so they know they're on track before they move on. +*/} + +[One sentence that says what the reader will do in this step.] + +1. [Step] + + ```bash + [command] + ``` + +2. [Step] + + ```bash + [command] + ``` + + You should see output like this: + + ``` + [expected output] + ``` + +## Step 2: [Verb] [object] + +## Step [N]: Clean up + +{/* + REQUIRED: Clean up + + Remove everything the tutorial created, in the reverse order it was created. + If the reader created a disposable cluster, deleting it is enough. +*/} + +1. [Step] + + ```bash + [command] + ``` + +## Summary + +{/* + OPTIONAL: Summary + + In a short list, remind the reader what they built and what they learned. +*/} + +## Next steps + +{/* + RECOMMENDED: Next steps + + Link to the one or two pages a reader is most likely to need next. + Good choices are the how-to guide for doing this in their own environment, and the explanation page for the feature. +*/} + +- [Link to a how-to guide] +- [Link to an explanation page] + +{/* + REVIEWER CHECKLIST + + - The title says what the reader will build or do, without a "Tutorial:" prefix. + - The first sentence uses the word "tutorial" and states what the reader will learn. + - Before you begin lists every tool, with links to install it. + - Step headings use the format "Step 1: [Verb] [object]". + - Every step works as written, with every name and value given. + - Each step section ends with a checkpoint that shows the expected output. + - Explanation is short, and longer explanation is linked. + - The tutorial ends with a clean-up step. + - Someone new to the feature has completed the tutorial from start to finish. +*/} diff --git a/contributors/style-guide.md b/contributors/style-guide.md new file mode 100644 index 0000000000..9c782ee3a5 --- /dev/null +++ b/contributors/style-guide.md @@ -0,0 +1,5 @@ +# Style guide + +Writing conventions for Calico documentation. + +TODO From e3213313f7695ac436ac0f95bf2cd4ff07ca83cd Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Wed, 4 Nov 2026 13:20:22 +0000 Subject: [PATCH 2/3] DOCS-3147: Quote template description placeholders Quote the description placeholder in each template so that it parses as a string. Remove sidebar_label guidance from the installation guide template. --- contributors/content-types/templates/explanation.mdx | 2 +- contributors/content-types/templates/how-to.mdx | 2 +- contributors/content-types/templates/installation-guide.mdx | 5 ++--- contributors/content-types/templates/reference.mdx | 2 +- contributors/content-types/templates/troubleshooting.mdx | 2 +- contributors/content-types/templates/tutorial.mdx | 2 +- 6 files changed, 7 insertions(+), 8 deletions(-) diff --git a/contributors/content-types/templates/explanation.mdx b/contributors/content-types/templates/explanation.mdx index 5a4997e603..943c1bff3f 100644 --- a/contributors/content-types/templates/explanation.mdx +++ b/contributors/content-types/templates/explanation.mdx @@ -1,5 +1,5 @@ --- -description: [What the reader will understand after reading this page, in one sentence of 130 to 160 characters. Use the full product name.] +description: "[What the reader will understand after reading this page, in one sentence of 130 to 160 characters. Use the full product name.]" --- {/* diff --git a/contributors/content-types/templates/how-to.mdx b/contributors/content-types/templates/how-to.mdx index 6a0c6bc713..902190ef8e 100644 --- a/contributors/content-types/templates/how-to.mdx +++ b/contributors/content-types/templates/how-to.mdx @@ -1,5 +1,5 @@ --- -description: [What the reader will get done by following this page, in one sentence of 130 to 160 characters. Use the full product name.] +description: "[What the reader will get done by following this page, in one sentence of 130 to 160 characters. Use the full product name.]" --- {/* diff --git a/contributors/content-types/templates/installation-guide.mdx b/contributors/content-types/templates/installation-guide.mdx index 98de828b7b..1bd303498c 100644 --- a/contributors/content-types/templates/installation-guide.mdx +++ b/contributors/content-types/templates/installation-guide.mdx @@ -1,5 +1,5 @@ --- -description: [What the reader will install and on which platform, in one sentence of 130 to 160 characters. Use the full product name.] +description: "[What the reader will install and on which platform, in one sentence of 130 to 160 characters. Use the full product name.]" --- {/* @@ -39,7 +39,6 @@ description: [What the reader will install and on which platform, in one sentenc REQUIRED: Title Use "Install $[prodname] on [platform]". - Put the platform name on its own in sidebar_label, so the sidebar lists platforms. */} [One or two sentences that say what the reader will install and on which platform.] @@ -166,7 +165,7 @@ description: [What the reader will install and on which platform, in one sentenc {/* REVIEWER CHECKLIST - - The title is "Install $[prodname] on [platform]", and sidebar_label is the platform name. + - The title is "Install $[prodname] on [platform]". - The lead paragraph says what the reader will install, and what's different about this platform. - Before you begin links to the compatibility and system requirements pages. - Every step is an instruction, with any condition first. diff --git a/contributors/content-types/templates/reference.mdx b/contributors/content-types/templates/reference.mdx index c51b065ace..9b51aef1e0 100644 --- a/contributors/content-types/templates/reference.mdx +++ b/contributors/content-types/templates/reference.mdx @@ -1,5 +1,5 @@ --- -description: [What the reader can look up on this page, in one sentence of 130 to 160 characters. Use the full product name.] +description: "[What the reader can look up on this page, in one sentence of 130 to 160 characters. Use the full product name.]" --- {/* diff --git a/contributors/content-types/templates/troubleshooting.mdx b/contributors/content-types/templates/troubleshooting.mdx index 24818b7501..ca6bc768ce 100644 --- a/contributors/content-types/templates/troubleshooting.mdx +++ b/contributors/content-types/templates/troubleshooting.mdx @@ -1,5 +1,5 @@ --- -description: [The problems this page helps the reader fix, in one sentence of 130 to 160 characters. Use the full product name.] +description: "[The problems this page helps the reader fix, in one sentence of 130 to 160 characters. Use the full product name.]" --- {/* diff --git a/contributors/content-types/templates/tutorial.mdx b/contributors/content-types/templates/tutorial.mdx index 413eb0fcf6..dfd7a7b34b 100644 --- a/contributors/content-types/templates/tutorial.mdx +++ b/contributors/content-types/templates/tutorial.mdx @@ -1,5 +1,5 @@ --- -description: [What the reader will build or learn by following this tutorial, in one sentence of 130 to 160 characters. Use the full product name.] +description: "[What the reader will build or learn by following this tutorial, in one sentence of 130 to 160 characters. Use the full product name.]" --- {/* From 747eeace715fc65288a8709335fd9012b3a73dd6 Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Thu, 5 Nov 2026 15:43:15 +0000 Subject: [PATCH 3/3] DOCS-3147: Tell coding agents to use the templates for new pages AGENTS.md applies only when an agent creates a new page. It points at the content types guide and the templates, and tells the agent not to restructure existing pages. CLAUDE.md imports it, so Claude Code reads the same file. Each template now sets content_type in its front matter, so a page copied from a template carries its type. --- AGENTS.md | 38 +++++++++++++++++++ CLAUDE.md | 1 + .../content-types/templates/explanation.mdx | 1 + .../content-types/templates/how-to.mdx | 1 + .../templates/installation-guide.mdx | 1 + .../content-types/templates/reference.mdx | 1 + .../templates/troubleshooting.mdx | 1 + .../content-types/templates/tutorial.mdx | 1 + 8 files changed, 45 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..066503226f --- /dev/null +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/contributors/content-types/templates/explanation.mdx b/contributors/content-types/templates/explanation.mdx index 943c1bff3f..91809d705b 100644 --- a/contributors/content-types/templates/explanation.mdx +++ b/contributors/content-types/templates/explanation.mdx @@ -1,5 +1,6 @@ --- 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 --- {/* diff --git a/contributors/content-types/templates/how-to.mdx b/contributors/content-types/templates/how-to.mdx index 902190ef8e..afecec90ec 100644 --- a/contributors/content-types/templates/how-to.mdx +++ b/contributors/content-types/templates/how-to.mdx @@ -1,5 +1,6 @@ --- description: "[What the reader will get done by following this page, in one sentence of 130 to 160 characters. Use the full product name.]" +content_type: how-to --- {/* diff --git a/contributors/content-types/templates/installation-guide.mdx b/contributors/content-types/templates/installation-guide.mdx index 1bd303498c..f12fdcdb70 100644 --- a/contributors/content-types/templates/installation-guide.mdx +++ b/contributors/content-types/templates/installation-guide.mdx @@ -1,5 +1,6 @@ --- description: "[What the reader will install and on which platform, in one sentence of 130 to 160 characters. Use the full product name.]" +content_type: installation-guide --- {/* diff --git a/contributors/content-types/templates/reference.mdx b/contributors/content-types/templates/reference.mdx index 9b51aef1e0..d6a51e36b2 100644 --- a/contributors/content-types/templates/reference.mdx +++ b/contributors/content-types/templates/reference.mdx @@ -1,5 +1,6 @@ --- description: "[What the reader can look up on this page, in one sentence of 130 to 160 characters. Use the full product name.]" +content_type: reference --- {/* diff --git a/contributors/content-types/templates/troubleshooting.mdx b/contributors/content-types/templates/troubleshooting.mdx index ca6bc768ce..1242dd68d2 100644 --- a/contributors/content-types/templates/troubleshooting.mdx +++ b/contributors/content-types/templates/troubleshooting.mdx @@ -1,5 +1,6 @@ --- description: "[The problems this page helps the reader fix, in one sentence of 130 to 160 characters. Use the full product name.]" +content_type: troubleshooting --- {/* diff --git a/contributors/content-types/templates/tutorial.mdx b/contributors/content-types/templates/tutorial.mdx index dfd7a7b34b..cb769dc051 100644 --- a/contributors/content-types/templates/tutorial.mdx +++ b/contributors/content-types/templates/tutorial.mdx @@ -1,5 +1,6 @@ --- description: "[What the reader will build or learn by following this tutorial, in one sentence of 130 to 160 characters. Use the full product name.]" +content_type: tutorial --- {/*