Technical Writer — Style Guide
| Field | Value |
|---|---|
| Type | Agent Reference |
| Source | ~/.copilot/agents/_refs/se-technical-writer/style-guide.md |
| Description | Not specified |
Source Content
Technical Writer — Style Guide
Audience adaptation, voice/tone, formatting, and quality rules. Apply alongside the templates in templates.md.
Audience Adaptation
| Audience | What they want | Tone | Depth signal |
|---|---|---|---|
| Junior developers | Context, definitions, the “why” | Encouraging, patient | Define terms on first use; explain motivations |
| Senior engineers | Implementation patterns, tradeoffs | Direct, peer-to-peer | Skip basics; show decisions and alternatives |
| Technical leaders | Strategic implications, architectural impact | Concise, outcome-framed | Lead with consequences; defer mechanics |
| Non-technical stakeholders | Business value, outcomes | Plain, analogy-driven | Replace jargon; visualize impact |
Style and Tone by Document Type
- Technical blogs — conversational yet authoritative; use “I” / “we” to create connection; lead with a hook.
- Reference docs — clear, direct, objective; consistent terminology; no narrative voice.
- Tutorials — encouraging, practical, step-by-step; verify after each step.
- Architecture docs / ADRs — precise, systematic, decision-focused; record context and tradeoffs.
- User guides — task-oriented; lead with the user’s goal; show outcomes.
Writing Principles
Clarity first
- Use simple words for complex ideas.
- Define technical terms on first use.
- One main idea per paragraph.
- Short sentences when explaining difficult concepts.
Structure and flow
- Start with the “why” before the “how”.
- Progressive disclosure — simple → complex.
- Signpost transitions (“First…”, “Next…”, “Finally…”).
- End sections with key takeaways.
Engagement
- Open with a hook that establishes relevance.
- Concrete examples over abstract explanations.
- Include lessons learned and failure stories where honest.
Technical accuracy
- All code examples must compile/run on the stated stack.
- Pin version numbers and dependencies; flag if version-sensitive.
- Cross-reference official documentation rather than restating it.
- Include performance implications where relevant.
Voice and Tone Rules
- Active voice — “The function processes data”, not “Data is processed by the function”.
- Direct address — use “you” when instructing.
- Inclusive language — “we discovered” for shared work; reserve “I” for personal narrative.
- Confident but humble — “this approach works well”, not “this is the best approach”.
Formatting Conventions
- Headers — Title Case for H1–H2, sentence case for H3+.
- Lists — bullets for unordered, numbers for sequences.
- Emphasis — bold for UI elements; italics for first use of terms.
- Code — backticks for inline, fenced blocks with language identifier for multi-line.
- Commands — show command and expected output.
- File paths — pick relative or absolute and stay consistent within the doc.
- Versions — include version numbers for tools, libraries, and APIs.
Common Pitfalls
Content
- Starting with implementation before explaining the problem.
- Assuming too much prior knowledge.
- Missing the “so what?” — failing to explain implications.
- Overwhelming with options instead of recommending defaults.
Technical
- Untested code examples.
- Outdated version references.
- Platform-specific assumptions without noting them.
- Security anti-patterns in example code.
Writing
- Passive-voice overuse making content feel distant.
- Jargon without definitions.
- Walls of text without visual breaks.
- Inconsistent terminology between sections.
Quality Checklist
Before shipping, verify:
- Clarity — a junior developer can follow the main points.
- Accuracy — all technical details and examples actually work.
- Completeness — promised topics are covered.
- Usefulness — readers can apply what they learned.
- Engagement — would you want to read this?
- Accessibility — readable for non-native English speakers.
- Scannability — readers can find what they need quickly.
- References — sources cited and links provided.
Specialized Focus Areas
Developer experience (DX) docs
- Onboarding guides that reduce time-to-first-success.
- API docs that anticipate common questions.
- Error messages that suggest solutions.
- Migration guides that handle edge cases.
Blog series
- Consistent voice across posts.
- Reference previous posts naturally.
- Build complexity progressively.
- Include series navigation.
Architecture docs
- ADRs (use the ADR template).
- System design docs with diagram references.
- Performance benchmarks with methodology.
- Security considerations with threat models.
User guides
- Task-oriented (use the user-guide template).
- Installation and setup docs.
- Feature-specific how-to guides.
- Admin and configuration guides.