Skip to content
Documentation

Technical Writer — Templates

FieldValue
TypeAgent Reference
Source~/.copilot/agents/_refs/se-technical-writer/templates.md
DescriptionNot specified

Source Content

Technical Writer — Templates

Reusable skeletons for the document types this agent produces. Pick one, fill in, then run the workflow’s review and verification steps.

1. Technical Blog Post

# [Compelling Title That Promises Value]


[Hook — problem or interesting observation]
[Stakes — why this matters now]
[Promise — what reader will learn]


## The Challenge


[Specific problem with context]
[Why existing solutions fall short]


## The Approach


[High-level solution overview]
[Key insights that made it possible]


## Implementation Deep Dive


[Technical details with code examples]
[Decision points and tradeoffs]


## Results and Metrics


[Quantified improvements]
[Unexpected discoveries]


## Lessons Learned


[What worked well]
[What we'd do differently]


## Next Steps


[How readers can apply this]
[Resources for going deeper]

2. Reference Documentation

# [Feature/Component Name]


## Overview


[What it does in one sentence]
[When to use it]
[When NOT to use it]


## Quick Start


[Minimal working example]
[Most common use case]


## Core Concepts


[Essential understanding needed]
[Mental model for how it works]


## API Reference


[Complete interface documentation]
[Parameter descriptions]
[Return values]


## Examples


[Common patterns]
[Advanced usage]
[Integration scenarios]


## Troubleshooting


[Common errors and solutions]
[Debug strategies]
[Performance tips]

3. Tutorial

# Learn [Skill] by Building [Project]


## What We're Building


[Visual/description of end result]
[Skills you'll learn]
[Prerequisites]


## Step 1: [First Tangible Progress]


[Why this step matters]
[Code/commands]
[Verify it works]


## Step 2: [Build on Previous]


[Connect to previous step]
[New concept introduction]
[Hands-on exercise]


[Continue steps...]


## Going Further


[Variations to try]
[Additional challenges]
[Related topics to explore]

4. Architecture Decision Record (ADR)

Follow the Michael Nygard ADR format.

# ADR-[Number]: [Short Title of Decision]


**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date**: YYYY-MM-DD
**Deciders**: [List key people involved]


## Context


[What forces are at play? Technical, organizational, political? What needs must be met?]


## Decision


[What's the change we're proposing/have agreed to?]


## Consequences


**Positive:**


- [What becomes easier or better?]


**Negative:**


- [What becomes harder or worse?]
- [What tradeoffs are we accepting?]


**Neutral:**


- [What changes but is neither better nor worse?]


## Alternatives Considered


**Option 1**: [Brief description]


- Pros: [Why this could work]
- Cons: [Why we didn't choose it]


## References


- [Links to related docs, RFCs, benchmarks]

ADR best practices:

  • One decision per ADR — keep focused.
  • Immutable once accepted — new context = new ADR.
  • Include metrics/data that informed the decision.
  • Reference: ADR GitHub organization.

5. User Guide

# [Product/Feature] User Guide


## Overview


**What is [Product]?**: [One sentence explanation]
**Who is this for?**: [Target user personas]
**Time to complete**: [Estimated time for key workflows]


## Getting Started


### Prerequisites


- [System requirements]
- [Required accounts/access]
- [Knowledge assumed]


### First Steps


1. [Most critical setup step with why it matters]
2. [Second critical step]
3. [Verification: "You should see..."]


## Common Workflows


### [Primary Use Case 1]


**Goal**: [What user wants to accomplish]
**Steps**:


1. [Action with expected result]
2. [Next action]
3. [Verification checkpoint]


**Tips**:


- [Shortcut or best practice]
- [Common mistake to avoid]


### [Primary Use Case 2]


[Same structure as above]


## Troubleshooting


| Problem                | Solution                      |
| ---------------------- | ----------------------------- |
| [Common error message] | [How to fix with explanation] |
| [Feature not working]  | [Check these 3 things...]     |


## FAQs


**Q: [Most common question]?**
A: [Clear answer with link to deeper docs if needed]


## Additional Resources


- [Link to API docs/reference]
- [Link to video tutorials]
- [Community forum/support]

User guide best practices:

  • Task-oriented, not feature-oriented (“How to export data” not “Export feature”).
  • Include screenshots for UI-heavy steps (reference image paths).
  • Test with actual users before publishing.
  • Reference: Write the Docs guide.