From 8859812f21933214211948e1cbc99725d9232fa4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 6 Jan 2026 17:05:58 -0800 Subject: [PATCH 1/3] add templates --- docs.json | 1 + guides/content-templates.mdx | 262 +++++++++++++++++++++++++++++++++++ 2 files changed, 263 insertions(+) create mode 100644 guides/content-templates.mdx diff --git a/docs.json b/docs.json index 89b194877..62b2e5bcd 100644 --- a/docs.json +++ b/docs.json @@ -270,6 +270,7 @@ "pages": [ "guides/accessibility", "guides/content-types", + "guides/content-templates", "guides/improving-docs", "guides/maintenance", "guides/media", diff --git a/guides/content-templates.mdx b/guides/content-templates.mdx new file mode 100644 index 000000000..0ae57c630 --- /dev/null +++ b/guides/content-templates.mdx @@ -0,0 +1,262 @@ +--- +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. + + + Not sure which template to use? Read about [content types](/guides/content-types) to understand when to use each one. + + +## 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 +``` + + + Include practical tips that help users avoid common mistakes or work more efficiently. + + +## 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. + + + Diagram showing how [concept] works + + +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 + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `property1` | `string` | Yes | Brief description of the property. | +| `property2` | `number` | No | Brief description with default value if applicable. | +| `property3` | `boolean` | No | Brief description. Defaults to `false`. | + +## Parameters + +### `parameterName` + +**Type**: `string` + +Description of what this parameter does and when to use it. + +```language +// Example showing typical usage +``` + +### `anotherParameter` + +**Type**: `object` + +Description of the parameter. + +Available options: + +- `option1`: Description of this option. +- `option2`: Description of this option. + +## 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 format + +If documenting an API, describe the response structure. + +```json +{ + "field1": "value", + "field2": 123 +} +``` + +## Related references + +Link to related reference documentation. +```` + +## Related pages + + + + Choose the right content type for your documentation goals. + + + Write effective documentation with consistent style. + + + Learn how to format text and style content. + + From e44d4634632b7d166b7aae91854880ce389eca5f Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 6 Jan 2026 17:06:05 -0800 Subject: [PATCH 2/3] update supporting docs --- guides/content-types.mdx | 6 +++++- guides/index.mdx | 1 + 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/guides/content-types.mdx b/guides/content-types.mdx index 1ee3bfcef..2c226ba00 100644 --- a/guides/content-types.mdx +++ b/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 + + Copy and modify templates for each content type. + Write effective documentation with consistent style. diff --git a/guides/index.mdx b/guides/index.mdx index 863cd95d0..eda9f7f37 100644 --- a/guides/index.mdx +++ b/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. From 7ef07e8b52ea60357fa0cdabe6d7a6b52dec15ad Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 6 Jan 2026 17:07:30 -0800 Subject: [PATCH 3/3] update reference template --- guides/content-templates.mdx | 48 ++++++++++++++++++++++-------------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/guides/content-templates.mdx b/guides/content-templates.mdx index 0ae57c630..fe7ce43a1 100644 --- a/guides/content-templates.mdx +++ b/guides/content-templates.mdx @@ -188,34 +188,36 @@ Provide a one-sentence description of what this feature or API does. ## Properties -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| `property1` | `string` | Yes | Brief description of the property. | -| `property2` | `number` | No | Brief description with default value if applicable. | -| `property3` | `boolean` | No | Brief description. Defaults to `false`. | + + Brief description of the property. + -## Parameters + + Brief description with default value if applicable. + -### `parameterName` + + Brief description. + -**Type**: `string` +## Parameters -Description of what this parameter does and when to use it. + + Description of what this parameter does and when to use it. ```language // Example showing typical usage ``` + -### `anotherParameter` - -**Type**: `object` - -Description of the parameter. + + Description of the parameter. -Available options: + Available options: -- `option1`: Description of this option. -- `option2`: Description of this option. + - `option1`: Description of this option. + - `option2`: Description of this option. + ## Examples @@ -231,10 +233,20 @@ Available options: // Example with multiple options configured ``` -## Response format +## Response If documenting an API, describe the response structure. + + Description of the response field. + + + + Description of another response field. + + +Example response: + ```json { "field1": "value",