Pro Writing Workspace

A comprehensive skill for technical and professional writing within development workflows. Covers documentation authoring, API documentation, changelog writing, RFC drafting, and writing style consistency for engineering teams.

When to Use This Skill

Choose this skill when:

• Writing technical documentation alongside code changes
• Drafting RFCs, design documents, or architectural proposals
• Creating changelogs, release notes, and migration guides
• Establishing writing style guides for engineering teams
• Editing existing documentation for clarity and accuracy

Consider alternatives when:

• Writing blog posts → use a content writing skill
• Creating user-facing help docs → use a documentation templates skill
• Writing code comments → handled inline during development
• Building a documentation site → use a static site generator skill

Quick Start

Copy
# Technical Writing Quick Reference

## Document Types and Templates
- **RFC:** Problem → Proposed Solution → Alternatives → Rollout Plan
- **ADR:** Context → Decision → Consequences
- **Changelog:** Added | Changed | Fixed | Removed | Security
- **Runbook:** When to use → Prerequisites → Steps → Troubleshooting
- **API Doc:** Endpoint → Parameters → Response → Errors → Examples

Copy
# Writing Style Checklist
- [ ] Active voice ("the server processes" not "is processed by")
- [ ] Present tense ("returns" not "will return")
- [ ] Second person for instructions ("you configure" not "the user configures")
- [ ] Concrete examples, not abstract descriptions
- [ ] One idea per sentence, one topic per paragraph
- [ ] Code samples that actually run

Core Concepts

Document Type Selection

Document	Audience	Purpose	When
README	New developers	Orientation	Project setup
API Reference	API consumers	Integration	Endpoint changes
Changelog	All users	What changed	Every release
RFC	Engineering team	Decision making	Before major changes
ADR	Future engineers	Decision context	After decisions
Runbook	On-call engineers	Incident response	Operational procedures
Migration Guide	Downstream teams	Upgrade path	Breaking changes

Changelog Best Practices (Keep a Changelog)

Copy
# Changelog

## [2.3.0] - 2024-03-15

### Added
- User profile photo upload with automatic resizing to 256x256
- Rate limiting on authentication endpoints (100 req/15min)

### Changed
- Updated password hashing from bcrypt cost 10 to cost 12
- Improved error messages for validation failures (now include field name)

### Fixed
- Fixed race condition in concurrent order submissions (#456)
- Resolved memory leak in WebSocket connection handler (#461)

### Security
- Patched CVE-2024-1234 in dependency `xml-parser` (upgraded to 3.2.1)

API Documentation Pattern

Copy
## Create Order

Creates a new order for the authenticated user.

**Endpoint:** `POST /api/v2/orders`

**Authentication:** Bearer token required

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `items` | `OrderItem[]` | Yes | Array of items to order |
| `items[].productId` | `string` | Yes | Product UUID |
| `items[].quantity` | `integer` | Yes | Quantity (1-999) |
| `shippingAddressId` | `string` | No | Saved address UUID |
| `couponCode` | `string` | No | Discount coupon code |

**Response (201 Created):**
```json
{
  "id": "ord_abc123",
  "status": "pending",
  "total": 59.98,
  "items": [{"productId": "prod_xyz", "quantity": 2, "price": 29.99}],
  "createdAt": "2024-03-15T10:30:00Z"
}

Errors:

Status	Code	Description
400	INVALID_QUANTITY	Quantity must be between 1 and 999
404	PRODUCT_NOT_FOUND	Product ID does not exist
409	OUT_OF_STOCK	Requested quantity exceeds available stock
422	INVALID_COUPON	Coupon code expired or already used

## Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `writingStyle` | string | `'technical'` | Style: technical, conversational, or formal |
| `voicePreference` | string | `'active'` | Voice: active or passive |
| `personPreference` | string | `'second'` | Person: second (you) or third (the user) |
| `changelogFormat` | string | `'keepachangelog'` | Changelog: keepachangelog or conventional |
| `codeExamples` | boolean | `true` | Include runnable code examples |
| `maxSentenceLength` | number | `25` | Target maximum words per sentence |

## Best Practices

1. **Lead with what the reader needs to do, not background context** — Put the action first, explanation second. "Run `npm install` to install dependencies" before "The project uses npm for package management." Readers scan for actions.

2. **Include complete, runnable code examples** — Snippets that require guessing imports, setup, or context frustrate readers. Every code example should work if copied and pasted with minimal surrounding context.

3. **Write error documentation with the same care as success paths** — Developers spend more time debugging errors than reading success flows. Document every error code, its cause, and the specific fix. "400 Bad Request" without details is useless.

4. **Update documentation in the same PR as code changes** — Documentation that lives in a separate repo or update cycle always drifts out of date. Co-locate docs with code and make doc updates part of the Definition of Done.

5. **Use tables for structured information, prose for explanations** — Parameters, error codes, and configuration options belong in tables. Conceptual explanations, motivations, and workflows belong in prose. Match the format to the content type.

## Common Issues

**Documentation is accurate but nobody reads it** — Long walls of text without structure or visual hierarchy are skipped. Use headings, tables, bullet points, and code blocks. Put the most important information first and link to details.

**Code examples break after library updates** — Pin dependency versions in examples and include the date last verified. Better yet, run code examples as tests in CI so they break visibly when APIs change.

**Multiple conflicting versions of documentation exist** — Wikis, READMEs, Confluence pages, and inline comments all describe the same thing differently. Choose one source of truth per topic and delete or link the others.