Add content templates

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

@@ -1,6 +1,6 @@
 ---
 title: "Content types"
 description: "Choose the right content type for your documentation goals."
 keywords: ["Diátaxis", "tutorials", "how-tos", "reference", "explanation", "categorization"]
 ---
 
@@ -8,11 +8,11 @@
   This page explains different content types, when to use each one, and how to approach writing for each type.
 </Tip>
 
 Documentation should be organized around the specific goal you're trying to help people achieve. 
 
 ## Categorize using the Diátaxis framework
 
 The [Diátaxis framework](https://diataxis.fr) is a helpful guide for categorizing content based on your audience's needs. Documentation can generally be mapped into one of these types:
 
 1. Tutorials: Learning-oriented content for new users
 2. How-to guides: Task-oriented guidance for specific problems
@@ -29,44 +29,44 @@
 
 | Question                     | Tutorial             | How-To               | Reference            | Explanation          |
 |:-----------------------------|:---------------------|:---------------------|:---------------------|:---------------------|
 | What is the user's goal?      | Learn through practice | Solve a specific problem | Find precise information | Understand concepts |
 | What is the user's knowledge? | Beginner             | Intermediate         | Experienced         | Any level           |
 | What is the primary focus?    | Learning by doing    | Achieving a goal     | Providing information | Deepening understanding |
 | How is the content structured? | Step-by-step        | Problem-solution     | Organized facts     | Conceptual discussions |
 | Is it task-oriented?          | Yes, guided tasks    | Yes, specific tasks  | No, informational   | No, conceptual      |
 | Is it designed for linear progression? | Yes | No | No | No |
 
 ## Writing for each type
 
 ### Tutorials (Learning-oriented)
 
 - **Audience goal**: Learn something new through step-by-step instructions.
 - **Characteristics**: Sequential and assumes no prior knowledge.
 - **Writing approach**:
   - Set expectations of what the user will achieve after reading.
   - Use clear, incremental steps. Minimize choices that need to be made by the user.
   - Point out milestones along the way.
   - Minimize theory and focus on concrete actions.
 
 ### How-To Guides (Problem-oriented)
 
 - **Audience goal**: Perform a specific task correctly.
 - **Characteristics**: Goal-driven and assumes some prior knowledge.
 - **Writing approach**:
   - Write from the perspective of the user, not the product.
   - Describe a logical sequence and omit unnecessary details.
   - Minimize context beyond what is necessary.
 
 ### Reference (Information-oriented)
 
 - **Audience goal**: Find details about a product's functionality.
 - **Characteristics**: Unambiguous, product-focused, scannable.
 - **Writing approach**:
   - Be scannable and concise.
   - Prioritize consistency.
   - Avoid explanatory content. Focus on examples that are easy to copy and modify.
 
 ### Explanation (Understanding-oriented)
 
 - **Audience goal**: Expand general understanding of a concept or highly complex feature.
 - **Characteristics**: Theoretical, potentially opinionated, broad in scope.
@@ -77,15 +77,19 @@
 
 ## 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 @@
 
 - [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.