Add content templates (#2569)

* add templates

* update supporting docs

* update reference template

Author: ethanpalm

docs.json

@@ -270,6 +270,7 @@
                 "pages": [
                   "guides/accessibility",
                   "guides/content-types",
+                  "guides/content-templates",
                   "guides/improving-docs",
                   "guides/maintenance",
                   "guides/media",

guides/content-templates.mdx

@@ -0,0 +1,274 @@
+---
+title: "Content templates"
+description: "Copy and modify these templates to quickly create documentation for different content types."
+keywords: ["templates"]
+---
+
+Use these templates as starting points for creating documentation. Customize the templates for your documentation and your audience.
+
+1. Copy the template that matches your content type.
+2. Replace placeholders and example content with your actual content.
+3. Adjust sections as needed.
+4. Remove any sections that don't apply.
+
+<Tip>
+  Not sure which template to use? Read about [content types](/guides/content-types) to understand when to use each one.
+</Tip>
+
+## How-to guide template
+
+Use how-to guides when users need to accomplish a specific task and already have some familiarity with your product. How-tos are goal-driven and get straight to the solution.
+
+````mdx How-to guide template
+---
+title: "[Titles should start with a verb]"
+description: "[Do specific task] to [achieve outcome]."
+---
+
+Start with a brief statement of what this guide helps users accomplish.
+
+## Prerequisites (optional)
+
+List only what's necessary:
+
+- Required setup or configuration
+- Permissions needed
+- Related features that should be configured first
+
+## [Action-oriented heading describing the task]
+
+Provide direct instructions focused on achieving the goal.
+
+1. Open [location] and navigate to [specific place]
+2. Click [button or option]
+3. Enter [required information]
+4. Click [confirmation button]
+
+```language
+// Include code examples that users can copy and modify
+```
+
+<Tip>
+  Include practical tips that help users avoid common mistakes or work more efficiently.
+</Tip>
+
+## Verify the result (optional)
+
+If success is ambiguous, explain how users can confirm they completed the task successfully.
+
+## Troubleshooting (optional)
+
+Address common issues users might encounter:
+
+- **Problem description**: Solution or workaround
+- **Another common issue**: How to resolve it
+
+## Related tasks
+
+Link to related how-to guides or next steps.
+````
+
+## Tutorial template
+
+Use tutorials when you want to help new users learn through hands-on practice. Tutorials guide users step-by-step through a complete learning experience with a clear outcome.
+
+````mdx Tutorial template
+---
+title: "[Action verb] [specific outcome]"
+description: "Learn how to [specific outcome] by [method or approach]."
+---
+
+Use an introduction paragraph to explain what users will learn and what they'll be able to do after completing this tutorial.
+
+## Prerequisites
+
+List what users need before starting:
+
+- Required knowledge or skills
+- Tools, accounts, or permissions
+- Time commitment (optional)
+
+## Step 1: [First action]
+
+Provide clear, specific instructions for the first step.
+
+```language
+// Include code examples where helpful
+```
+
+Explain what this step accomplishes and why it matters.
+
+## Step 2: [Second action]
+
+Continue with sequential steps that build on previous work.
+
+Point out milestones and progress markers so users know they're on track.
+
+## Step 3: [Third action]
+
+Keep steps focused on concrete actions rather than theory.
+
+Minimize choices that users need to make.
+
+## Next steps
+
+Summarize what users learned and suggest logical next steps:
+
+- Related tutorials to try
+- How-to guides for common tasks
+- Additional resources for deeper learning
+````
+
+## Explanation template
+
+Use explanations when users need to understand concepts, design decisions, or how complex features work. Explanations provide context and deepen understanding rather than giving step-by-step instructions.
+
+````mdx Explanation template
+---
+title: "About [concept or feature]"
+description: "Understand [concept] and how it works within [product or context]."
+---
+
+Start with a clear statement of what this explanation covers and why understanding it matters.
+
+Define the concept in plain language. Explain what it is, what it does, and why it exists.
+
+Use analogies or comparisons to familiar concepts when helpful.
+
+## How [concept] works
+
+Explain the underlying mechanics, architecture, or process.
+
+<Frame>
+  <img src="/path/to/diagram.png" alt="Diagram showing how [concept] works" />
+</Frame>
+
+Break down complex ideas into digestible sections.
+
+## Why [design decision or approach]
+
+Provide context about why things work the way they do.
+
+Discuss trade-offs, alternatives that were considered, or constraints that influenced the design.
+
+## When to use [concept]
+
+Help users understand when this concept or approach is most appropriate.
+
+- **Use case 1**: When this approach makes sense
+- **Use case 2**: Another scenario where this is the right choice
+- **Not recommended for**: Situations where alternatives are better
+
+## Relationship to other features
+
+Draw connections to related concepts or features in your product.
+
+Explain how this concept fits into the broader system or workflow.
+
+## Common misconceptions
+
+Address misunderstandings or clarify subtle distinctions.
+
+## Further reading
+
+Link to related explanations, tutorials, or reference documentation.
+````
+
+## Reference template
+
+Use reference documentation when users need to look up specific details about your product's functionality. Reference docs prioritize accuracy, consistency, and scannability.
+
+````mdx Reference template
+---
+title: "[Feature or API name] reference"
+description: "Complete reference for [feature or API] properties, parameters, and options."
+---
+
+Provide a one-sentence description of what this feature or API does.
+
+## Properties
+
+<ParamField body="property1" type="string" required>
+  Brief description of the property.
+</ParamField>
+
+<ParamField body="property2" type="number">
+  Brief description with default value if applicable.
+</ParamField>
+
+<ParamField body="property3" type="boolean" default="false">
+  Brief description.
+</ParamField>
+
+## Parameters
+
+<ParamField body="parameterName" type="string">
+  Description of what this parameter does and when to use it.
+
+```language
+// Example showing typical usage
+```
+</ParamField>
+
+<ParamField body="anotherParameter" type="object">
+  Description of the parameter.
+
+  Available options:
+
+  - `option1`: Description of this option.
+  - `option2`: Description of this option.
+</ParamField>
+
+## Examples
+
+### Basic example
+
+```language title="Basic usage"
+// Minimal example showing common use case
+```
+
+### Advanced example
+
+```language title="Advanced configuration"
+// Example with multiple options configured
+```
+
+## Response
+
+If documenting an API, describe the response structure.
+
+<ResponseField name="field1" type="string" required>
+  Description of the response field.
+</ResponseField>
+
+<ResponseField name="field2" type="number">
+  Description of another response field.
+</ResponseField>
+
+Example response:
+
+```json
+{
+  "field1": "value",
+  "field2": 123
+}
+```
+
+## Related references
+
+Link to related reference documentation.
+````
+
+## Related pages
+
+<CardGroup cols={2}>
+  <Card title="Content types" icon="shapes" href="/guides/content-types">
+    Choose the right content type for your documentation goals.
+  </Card>
+  <Card title="Style and tone" icon="pen" href="/guides/style-and-tone">
+    Write effective documentation with consistent style.
+  </Card>
+  <Card title="Format text" icon="text" href="/create/text">
+    Learn how to format text and style content.
+  </Card>
+</CardGroup>

guides/content-types.mdx

@@ -77,15 +77,19 @@ Defining content types helps you plan documentation with a clear purpose and mak
 
 ## Tips and tricks
 
-1. **Maintain purpose**: Before writing, assign each page a specific content type and make it top of mind in the doc throughout your writing. 
+1. **Maintain purpose**: Before writing, assign each page a specific content type and make it top of mind in the doc throughout your writing.
 2. **Consider content freshness**: Regardless of content type, try to optimize for evergreen documentation. If something represents a moment in time of what a feature looks like on a specific date, it's probably better suited for a changelog or blog post than in your documentation. Or if something changes very frequently avoid putting it in your docs.
 3. **Think like your users**: Consider different user personas when organizing content. See [Understand your audience](/guides/understand-your-audience) for more information.
+4. **Use templates**: Start with [content templates](/guides/content-templates) that provide the basic structure for each content type.
 
 While the Diátaxis framework provides a starting point, successful documentation requires contextual adaptation to your product. Start by understanding the framework's principles, then adjust them to serve your users' needs.
 
 ## Related pages
 
 <CardGroup cols={2}>
+  <Card title="Content templates" icon="file-code" href="/guides/content-templates">
+    Copy and modify templates for each content type.
+  </Card>
   <Card title="Style and tone" icon="pen" href="/guides/style-and-tone">
     Write effective documentation with consistent style.
   </Card>

guides/index.mdx

@@ -30,6 +30,7 @@ Make your documentation best in class.
 
 - [Accessibility](/guides/accessibility): Make your docs accessible to as many users as possible.
 - [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations.
+- [Content templates](/guides/content-templates): Copy and modify templates for each content type.
 - [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve your documentation.
 - [Maintenance](/guides/maintenance): Keep your documentation accurate and up-to-date.
 - [Media](/guides/media): Add images, videos, and other media effectively while managing maintenance burden.