| name | technical-writing |
| description | Technical writing skills for blogs, documentation, and developer content |
| sasmp_version | 1.4.0 |
| version | 2.0.0 |
| updated | 2025-01 |
| bonded_agent | 04-technical-writer |
| bond_type | PRIMARY_BOND |
Technical Writing for DevRel
Create clear, effective technical content for developer audiences.
Skill Contract
Parameters
parameters:
required:
- content_type: enum[blog, docs, tutorial, api_reference]
- topic: string
optional:
- word_count_target: integer
- seo_keywords: array[string]
- code_language: string
Output
output:
content:
title: string
body: markdown
meta_description: string
quality:
readability_score: float
code_tested: boolean
Writing Principles
Clarity First
Bad: "The utilization of the aforementioned methodology..."
Good: "Use this method to..."
Bad: "It is recommended that developers should..."
Good: "You should..."
Structure for Scanning
# Main Topic (H1 - one per page)
Brief intro paragraph explaining what and why.
## Section (H2 - major topics)
One paragraph context.
### Subsection (H3 - specific items)
- Bullet points for lists
- Code blocks for examples
- Tables for comparisons
Content Types
| Type | Purpose | Structure |
|---|
| Tutorial | Teach task | Step-by-step |
| How-to | Solve problem | Problem→Solution |
| Concept | Explain idea | What→Why→How |
| Reference | Look up info | Alphabetical/API |
Blog Post Formula
1. Hook (problem/question)
2. Promise (what they'll learn)
3. Context (why it matters)
4. Content (the meat)
5. Examples (code/demos)
6. Summary (key takeaways)
7. CTA (what to do next)
SEO for Technical Content
- Keyword in title and H1
- Keywords in first paragraph
- Meta description (150-160 chars)
- Internal linking
- Code snippets for featured snippets
Retry Logic
retry_patterns:
code_sample_fails:
strategy: "Test in clean environment"
fallback: "Add version requirements note"
unclear_explanation:
strategy: "Rewrite with example first"
seo_not_ranking:
strategy: "Audit keywords, improve title"
Failure Modes & Recovery
| Failure Mode | Detection | Recovery |
|---|
| Code doesn't work | Reader reports | Hotfix, add version note |
| Outdated info | API changed | Update + deprecation notice |
| Poor engagement | Low time on page | Rewrite hook |
Debug Checklist
□ Code samples tested?
□ Links verified?
□ Images have alt text?
□ Consistent terminology?
□ Spell check completed?
□ Mobile-friendly formatting?
□ Meta description ready?
□ Clear CTA at end?
Test Template
test_technical_writing:
unit_tests:
- test_code_compiles:
assert: "Code runs without errors"
- test_links_valid:
assert: "200 OK response"
integration_tests:
- test_reader_journey:
assert: "Achieves stated outcome"
Quality Metrics
| Metric | Target |
|---|
| Readability | Flesch 60+ |
| Code accuracy | 100% working |
| Time on page | >3 min |
Observability
metrics:
- word_count: integer
- code_blocks_count: integer
- reading_time: duration
See assets/ for writing templates.
