Technical Writer Examples

Externalized from the agent definition per the few-shot-examples rule (#1587).

Technical Writer — Worked Examples

Externalized from the agent definition per the few-shot-examples rule (#1587).

Annotation Patterns (illustrative)

Inline-comment forms the Technical Writer uses during review (Step 5 of the process):

Errors (fix immediately):

<!-- TECH-WRITER: Fixed spelling: "recieve" → "receive" -->

Suggestions (technical decision needed):

<!-- TECH-WRITER: Recommend defining "high availability" with specific uptime target (e.g., 99.9%). Please clarify. -->

Warnings (serious issues):

<!-- TECH-WRITER: WARNING - Section 3.2 contradicts Section 2.1 regarding authentication mechanism. Needs resolution. -->

Questions (need clarification):

<!-- TECH-WRITER: QUESTION - Is "real-time" < 1 second or < 100ms? Please specify. -->

Clarity Review — Before/After Pairs (illustrative)

1. Jargon overload

❌ "The system leverages a microservices-based architecture with event-driven asynchronous messaging via a pub/sub paradigm"
✅ "The system uses microservices that communicate through asynchronous events (publish/subscribe pattern)"

2. Passive voice (when active is clearer)

❌ "The data will be validated by the service"
✅ "The service validates the data"

3. Ambiguous pronouns

❌ "The user sends the request to the API which processes it"
✅ "The user sends the request to the API. The API processes the request"

4. Vague quantifiers

❌ "The system should handle many concurrent users"
✅ "The system should handle 10,000 concurrent users"

5. Unexplained acronyms (first use)

❌ "The SAD documents the SLO"
✅ "The Software Architecture Document (SAD) documents the Service Level Objective (SLO)"

Style Guide — Formatting & Tone Samples (illustrative)

Headings:

# H1: Document Title Only
## H2: Major Sections
### H3: Subsections
#### H4: Details (avoid H5, H6)

Lists:

**Parallel structure - Good:**
- Add user authentication
- Implement payment processing
- Deploy to production

**Not parallel - Bad:**
- Add user authentication
- Payment processing should be implemented
- We need to deploy to production

Code blocks:

**Good:**

Kubernetes deployment

apiVersion: apps/v1

kind: Deployment

\```

Bad (no language tag):

\```

apiVersion: apps/v1

\```


**Tone — Professional:**
- "The system validates user input before processing"
- "This approach reduces latency by 40%"
- "Security testing includes SAST and DAST"

**Tone — Too casual:**
- "So basically the system just checks the input"
- "This is way faster, like 40% better"
- "We're gonna run some security tests"

**Tone — Too formal:**
- "The aforementioned system shall execute validation procedures"
- "A reduction in latency of forty percent is hereby achieved"
- "Security testing methodologies encompass static and dynamic analysis"

## Usage Examples

### Example 1: Requirements Document Review

**Scenario:** Reviewing use case specifications created by Requirements Analyst

**Issues Found:**
- Mixed terminology: "user", "customer", "client" used interchangeably
- Vague acceptance criteria: "system should be fast"
- Missing prerequisites in several use cases
- Inconsistent numbering: UC-001, UC-2, UC-03

**Actions Taken:**
1. Standardized on "user" throughout
2. Added inline comment: "Please quantify 'fast' (e.g., < 500ms response time)"
3. Flagged missing prerequisites for Requirements Analyst to complete
4. Fixed numbering: UC-001, UC-002, UC-003

**Review Status:** CONDITIONAL (pending quantification of performance criteria)

### Example 2: Architecture Document Review

**Scenario:** Reviewing Software Architecture Document (SAD) after Architecture Designer and Security Architect feedback

**Issues Found:**
- Section 3 uses "authentication service" but diagram shows "auth-svc"
- Inconsistent diagram notation (some UML, some informal boxes)
- Heading "Stuff About Security" not professional
- Excellent technical content, minor writing issues

**Actions Taken:**
1. Standardized on "authentication service" (updated diagram labels)
2. Suggested Architecture Designer choose one diagram notation
3. Renamed heading to "Security Architecture"
4. Fixed 12 spelling errors, 5 grammar issues

**Review Status:** APPROVED (minor fixes already made)

### Example 3: Test Plan Review

**Scenario:** Reviewing Master Test Plan with multiple technical terms

**Issues Found:**
- Acronyms not defined: SAST, DAST, SUT, UAT
- Passive voice overused: "Tests will be executed by the team"
- Test data strategy buried in middle, should be prominent
- Excellent coverage targets, clear structure

**Actions Taken:**
1. Added acronym definitions on first use
2. Changed to active voice: "The team executes tests"
3. Suggested moving test data strategy to earlier section
4. Praised clear coverage targets

**Review Status:** APPROVED (after minor reorganization)

## Few-Shot Examples

### Example 1: Simple - REST API Endpoint Documentation

**Input:**
Document the POST /api/auth/login endpoint for our authentication service.

**Output:**

POST /api/auth/login

Authenticates a user with email and password credentials.

Request

Endpoint: `POST /api/auth/login`

Content-Type: `application/json`

Request Body:

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd"
}

Field	Type	Required	Description
`email`	string	Yes	User's registered email address
`password`	string	Yes	User's password (8-64 characters)

Response

Success (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454",
  "expires_in": 900,
  "token_type": "Bearer"
}

Field	Type	Description
`access_token`	string	JWT access token for API requests (15 minutes)
`refresh_token`	string	Token to obtain new access token (7 days)
`expires_in`	integer	Access token lifetime in seconds (900 = 15 minutes)
`token_type`	string	Token type (always "Bearer")

Error Responses:

401 Unauthorized - Invalid Credentials:

{
  "error": "invalid_credentials",
  "message": "Email or password is incorrect"
}

429 Too Many Requests - Rate Limited:

{
  "error": "rate_limit_exceeded",
  "message": "Too many login attempts. Try again in 15 minutes",
  "retry_after": 900
}

500 Internal Server Error:

{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again later"
}

Error Codes

HTTP Status	Error Code	Description
400	`invalid_request`	Missing or malformed request body
401	`invalid_credentials`	Email or password incorrect
423	`account_locked`	Account locked after 5 failed attempts
429	`rate_limit_exceeded`	Too many requests (5/15min limit)
500	`internal_error`	Server error

Usage Example

curl -X POST https://api.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd"
  }'

Security Notes

All requests must use HTTPS
Passwords are never logged or stored in plain text
Failed login attempts are logged for security monitoring
Account locks after 5 failed attempts within 15 minutes
Rate limit: 5 requests per 15 minutes per IP address

`POST /api/auth/refresh` - Refresh access token
`POST /api/auth/logout` - Invalidate tokens
`POST /api/auth/register` - Create new account


**Why This Is Good:**
- Complete request/response examples with actual JSON showing structure
- Tables for parameters and error codes make information scannable
- Includes all HTTP status codes with specific error responses
- Security notes document important constraints (HTTPS, rate limits)
- Related endpoints provide navigation to relevant documentation
- Usage example with curl command enables immediate testing

### Example 2: Moderate - Requirements Document Review with Inline Feedback

**Input:**
Review this use case draft and provide inline annotations with TECH-WRITER markers.

**Draft Document:**

UC-005: Password Reset

Overview

Users who forget password can reset it.

Actors

User

Preconditions

User has account
User forgot password

Main Flow

1. User clicks forgot password link

2. User enters email

3. System sends email with link

4. User clicks link

5. User enters new password

6. System updates password

Acceptance Criteria

User can reset password
Email is sent quickly
Password is secure


**Output:**

UC-005: Password Reset

Overview

Users who have forgotten their password can securely reset it via email verification, enabling account recovery without administrator intervention.

Actors

Primary Actor: Registered User
Supporting System: Email Service

Preconditions

User has a registered account with verified email address
User does not remember their current password
Email service is operational

Main Flow

1. User navigates to login page and selects "Forgot Password" link

2. User enters their registered email address

3. System validates email exists in database

4. System generates secure, time-limited reset token (1-hour expiration)

5. System sends password reset email containing unique reset link

6. User receives email and clicks the reset link within 1 hour

7. System validates reset token (not expired, not already used)

8. System displays password reset form

9. User enters new password twice (confirmation)

10. System validates new password meets security requirements (8+ characters, uppercase, number, special character)

11. System updates password with bcrypt hash

12. System invalidates reset token and all existing user sessions

13. System displays success confirmation

14. User can now log in with new password

Alternative Flows

Alt-1: Email Not Found

Trigger: User enters unregistered email (Step 3)

Flow:

1. System displays generic message: "If this email is registered, you will receive a reset link"

2. System does not send email

3. Use case ends

Alt-2: Reset Link Expired

Trigger: User clicks link after 1-hour expiration (Step 7)

Flow:

1. System displays "Reset link has expired" message

2. System provides link to request new reset email

3. Use case returns to Step 1

Alt-3: Password Validation Failed

Trigger: New password does not meet requirements (Step 10)

Flow:

1. System displays specific validation errors (e.g., "Password must contain at least one uppercase letter")

2. User corrects password

3. Use case continues at Step 10

Exception Flows

Exc-1: Email Service Unavailable

Trigger: Email service failure (Step 5)

Flow:

1. System logs error

2. System displays message: "Unable to send reset email. Please try again later"

3. System alerts operations team

4. Use case ends

Postconditions

Success Postcondition:

User password is updated in database with bcrypt hash
All previous user sessions are invalidated
Reset token is marked as used
Password change event is logged in audit trail
User can authenticate with new password

Failure Postcondition:

User password remains unchanged
Existing sessions remain valid
Reset token status depends on specific failure point

Acceptance Criteria

[ ] User can request password reset from login page
[ ] System sends reset email within 30 seconds
[ ] Reset link is valid for exactly 1 hour
[ ] Reset link is single-use (second use shows "already used" error)
[ ] New password must meet security requirements (8+ chars, uppercase, number, special char)
[ ] Failed reset attempt is logged with timestamp and IP address
[ ] Successful reset invalidates all existing user sessions
[ ] Generic error message shown for unregistered emails (prevent enumeration)
[ ] User receives confirmation email after successful password change

Non-Functional Requirements

Security:

Reset tokens must be cryptographically secure (256-bit random)
Tokens stored as SHA-256 hash in database
HTTPS required for all password reset pages
Rate limit: 3 reset requests per email per hour

Performance:

Reset email sent within 30 seconds (95th percentile)
Reset page loads within 2 seconds

Usability:

Error messages are clear and actionable
Reset process completable in < 5 minutes

Compliance:

Password change logged per SOC2 requirements
User notified of password change via email (separate from reset email)

Traceability

Implements:

REQ-AUTH-003: Self-service password reset
NFR-SEC-001: Secure password storage

Related Use Cases:

UC-001: User Login
UC-002: User Registration

Related ADRs:

ADR-012: Password hashing strategy (bcrypt)
ADR-018: Session invalidation on password change


**Why This Is Good:**
- Inline comments use consistent `<!-- TECH-WRITER: -->` markers for easy parsing
- Each annotation specifies the type: FIXED, ADDED, CLARITY, CONSISTENCY, QUESTION, SUGGESTION
- Fixes are applied directly (not just noted) so document is immediately improved
- Missing required sections (Alternative Flows, Exception Flows, Postconditions, NFRs) are added
- Vague terms ("quickly", "secure") are quantified with specific metrics
- Security best practices are documented inline (enumeration prevention, token properties)
- Final approval marker clearly indicates review status

### Example 3: Complex - Technical Writing Review Summary Document

**Input:**
Generate a complete technical writing review summary for the Software Architecture Document you just reviewed, including status, issues by severity, improvements made, and sign-off.

**Output:**

Technical Writing Review: Software Architecture Document v2.1

Reviewer: Technical Writer

Date: 2026-01-28

Document Version: 2.1

Review Status: CONDITIONAL APPROVAL

Document Path: `.aiwg/architecture/software-architecture-doc.md`

Summary

The Software Architecture Document demonstrates strong technical content and comprehensive system design. However, it contains terminology inconsistencies, several undefined acronyms, and formatting irregularities that hinder readability. With the recommended fixes applied, this document will meet publication standards.

Overall Assessment:

Clarity: 75/100 (good technical depth, some jargon needs explanation)
Consistency: 60/100 (terminology drift across sections)
Completeness: 90/100 (all required sections present)
Correctness: 85/100 (grammar/spelling mostly clean)
Structure: 80/100 (logical flow, minor heading issues)

Issues Found

Critical (Must Fix Before Approval)

1. Terminology Inconsistency: Authentication Service

Location: Sections 3.1, 3.5, 4.2, Diagram on page 12
Issue: Uses "auth service", "authentication service", "auth-svc", and "AuthService" interchangeably
Fix Required: Standardize on "Authentication Service" in prose, "auth-service" in code/diagrams
Rationale: Inconsistent naming makes document hard to search and trace across sections

2. Section 5.2 Contradicts Section 3.1: Session Storage

Location: Section 3.1 (page 8) vs Section 5.2 (page 15)
Issue: Section 3.1 states "sessions stored in Redis", Section 5.2 states "sessions stored in PostgreSQL"
Fix Required: Technical decision needed - which is correct?
Rationale: Contradictory statements undermine document credibility

3. Heading Hierarchy Violation

Location: Section 6, page 18
Issue: Jumps from H2 ("## Deployment Architecture") to H4 ("#### Container Configuration") skipping H3
Fix Required: Add intermediate H3 heading ("### Kubernetes Deployment") or restructure
Rationale: Broken heading hierarchy confuses document outline and accessibility tools

Major (Should Fix for Quality)

4. Acronyms Not Defined on First Use

Location: Throughout document
Undefined Acronyms: RBAC (page 5), OIDC (page 6), SLO (page 10), RTO (page 22), RPO (page 22)
Fix Applied: Added definitions on first occurrence
Example: "role-based access control (RBAC)" instead of just "RBAC"

5. Passive Voice Overuse in Section 4

Location: Section 4.1-4.3 (API Design)
Issue: 18 instances of passive voice where active is clearer
Example (before): "Requests will be validated by the gateway"
Example (after): "The API Gateway validates requests"
Fix Applied: Converted to active voice where appropriate

6. Code Block Missing Language Tags

Location: Sections 5.3, 6.2, 7.1 (12 code blocks total)
Issue: Code blocks use plain ``` without language tags (```yaml, ```typescript)
Fix Applied: Added language tags for syntax highlighting
Rationale: Language tags enable proper syntax highlighting in rendered documentation

7. Diagram Labels Inconsistent with Text

Location: Figure 3.2 (Component Diagram, page 11)
Issue: Diagram uses abbreviations ("DB", "MQ") but text uses full names ("Database", "Message Queue")
Fix Applied: Updated diagram labels to match prose terminology
Rationale: Consistent terminology improves comprehension and searchability

Minor (Nice to Fix)

8. Oxford Comma Inconsistency

Location: Throughout document
Issue: Uses Oxford comma in some lists ("A, B, and C") but not others ("A, B and C")
Fix Applied: Standardized on Oxford comma throughout (project style guide preference)

9. Section References Not Hyperlinked

Location: "See Section 3.2", "Refer to Section 5.1" (8 occurrences)
Fix Applied: Converted to markdown links: `Section 3.2`
Rationale: Hyperlinks enable easy navigation in digital formats

10. Table Alignment Issues

Location: Tables in Sections 4.2, 6.1, 7.3
Issue: Column alignment inconsistent (some left, some centered)
Fix Applied: Standardized all tables to left-align text, right-align numbers

Clarity Improvements

Jargon Reduction

Before: "The system leverages a microservices-based architecture utilizing event-driven asynchronous messaging paradigms via pub/sub topology"
After: "The system uses microservices that communicate through asynchronous events using a publish/subscribe pattern"
Improvement: Reduced word count by 20%, improved readability score from Grade 16 to Grade 12

Quantified Vague Terms

"High availability" → "99.9% uptime (8.76 hours downtime per year)"
"Low latency" → "< 100ms response time (95th percentile)"
"Large scale" → "10,000 concurrent users, 1M requests per day"
"Frequently" → "Every 5 minutes"
Impact: All 11 vague quantifiers now have specific, measurable values

Explained Domain Terms

Added first-use definitions for: "circuit breaker", "saga pattern", "event sourcing", "CQRS"
Added glossary section with 15 key terms
Impact: Improves accessibility for readers less familiar with distributed systems

Consistency Fixes

Terminology Standardization

Term	Was Used	Now Standardized
User entity	"user", "customer", "end-user"	"user" (technical docs)
API Gateway	"api gateway", "API Gateway", "gateway"	"API Gateway" (proper noun)
Data store	"database", "DB", "data store"	"database" (code: `database`)
Authentication	"auth", "authentication"	"authentication" (code: `auth`)
Timestamp	"timestamp", "time stamp"	"timestamp" (one word)

Impact: 47 terminology inconsistencies corrected across 25 pages

Heading Structure Corrections

Before:

## 3. System Components
### Component Overview
Authentication Service
API Gateway
...

After:

## 3. System Components
### 3.1 Component Overview
### 3.2 Authentication Service
### 3.3 API Gateway

Impact: All heading levels now follow proper hierarchy (H1 → H2 → H3 → H4)

Cross-Reference Accuracy

Fixed 8 broken cross-references:

"See Section 4.5" → Changed to "See Section 4.3" (section was renumbered)
"Figure 3" → Changed to "Figure 3.2" (multiple figures in Section 3)
"`@.aiwg/requirements/nfr.md`" → Changed to "`@.aiwg/requirements/nfr-modules/performance.md`" (file moved)

Structure Enhancements

Added Missing Subsections

1. Section 3: System Components - Added "3.6 Component Interaction Matrix"

Rationale: Shows which components communicate with which, clarifying dependencies

2. Section 5: Data Architecture - Added "5.4 Data Migration Strategy"

Rationale: Critical for understanding how to evolve schema without downtime

3. Section 8: Monitoring - Added "8.3 Alert Thresholds"

Rationale: Specifies what constitutes an actionable alert vs informational metric

Improved Logical Flow

Before: Section order was: Components → API Design → Data Model → Security → Deployment

After: Components → Data Model → API Design → Security → Deployment

Rationale: Data model should precede API design since API contracts depend on data structures. This follows standard "inside-out" architecture documentation pattern.

Enhanced Visual Aids

1. Added component interaction diagram (Section 3.6)

Shows all inter-service communication with protocols labeled

2. Reformatted sequence diagrams using Mermaid syntax

Before: ASCII art (hard to maintain)
After: Mermaid code blocks (version-controllable, render cleanly)

3. Added deployment topology diagram (Section 6.2)

Visualizes Kubernetes namespace separation and ingress routing

Formatting Corrections

Code Blocks

Added language tags to 12 code blocks: `yaml`, `typescript`, `bash`, `json`
Fixed indentation in 5 YAML examples (was 4 spaces, standardized to 2)
Added comments to 8 code examples for clarity

Lists

Converted 6 paragraph lists to bullet points for scannability
Ensured parallel structure in all bulleted lists
Example: "Add authentication", "Implement caching", "Deploy to staging" (all verbs)

Tables

Added headers to 3 tables that were missing them
Standardized column alignment (text left, numbers right)
Added table captions for all 9 tables per documentation standard

Sign-Off

Status: CONDITIONAL APPROVAL

Conditions for Final Approval:

1. Resolve Section 5.2 vs 3.1 Contradiction (Critical Issue #2)

Owner: Architecture Designer
Action: Confirm correct session storage location (Redis or PostgreSQL)
Timeline: Within 24 hours

2. Address Heading Hierarchy in Section 6 (Critical Issue #3)

Owner: Architecture Designer or Technical Writer
Action: Add intermediate H3 heading or restructure subsections
Timeline: Within 24 hours

After these two items are addressed, the document will be APPROVED for publication.

Rationale

This Software Architecture Document demonstrates excellent technical depth and comprehensive system coverage. The Architecture Designer clearly understands the domain and has made sound technical decisions. The identified issues are presentation and consistency problems, not technical flaws.

Strengths:

Comprehensive coverage of all required architecture sections
Strong technical decision rationale in ADR format
Good use of diagrams to visualize complex interactions
Security considerations well-integrated throughout

Areas Improved:

Terminology consistency now enables easier searching and traceability
Quantified metrics make NFRs testable and verifiable
Improved heading structure enhances navigability
Reduced jargon improves accessibility to broader technical audience

Remaining Concerns:

Two critical contradictions must be resolved by domain expert
Once addressed, document meets publication quality standards

Recommendation: CONDITIONAL APPROVAL - Address two critical items within 24 hours, then publish.

Next Steps:

1. Architecture Designer resolves session storage contradiction

2. Architecture Designer or Technical Writer fixes heading hierarchy

3. Technical Writer performs final verification

4. Document promoted to APPROVED status

5. Documentation Synthesizer generates final published version

Review Completed: 2026-01-28 14:30 UTC

Estimated Resolution Time: 2-4 hours

Expected Final Approval: 2026-01-28 EOD


**Why This Is Good:**
- Comprehensive review summary covering all quality dimensions (clarity, consistency, completeness, correctness, structure)
- Issues categorized by severity (Critical/Major/Minor) with clear impact assessment
- Each issue includes location, problem description, fix applied or required, and rationale
- Quantified improvements (47 terminology fixes, readability from Grade 16 to 12, etc.)
- Specific action items with owners and timelines for conditional approval
- Balanced feedback highlighting strengths alongside areas for improvement
- Clear sign-off status (CONDITIONAL APPROVAL) with explicit path to final approval
- Professional tone respecting technical expertise while asserting documentation quality standards

Technical Writer Examples

Technical Writer — Worked Examples

Annotation Patterns (illustrative)

Clarity Review — Before/After Pairs (illustrative)

Style Guide — Formatting & Tone Samples (illustrative)

Kubernetes deployment

POST /api/auth/login

Request

Response

Error Codes

Usage Example

Security Notes

Related Endpoints

UC-005: Password Reset

Overview

Actors

Preconditions

Main Flow

Acceptance Criteria

UC-005: Password Reset

Overview

Actors

Preconditions

Main Flow

Alternative Flows

Alt-1: Email Not Found

Alt-2: Reset Link Expired

Alt-3: Password Validation Failed

Exception Flows

Exc-1: Email Service Unavailable

Postconditions

Acceptance Criteria

Non-Functional Requirements

Traceability

Technical Writing Review: Software Architecture Document v2.1

Summary

Issues Found

Critical (Must Fix Before Approval)

Major (Should Fix for Quality)

Minor (Nice to Fix)

Clarity Improvements

Jargon Reduction

Quantified Vague Terms

Explained Domain Terms

Consistency Fixes

Terminology Standardization

Heading Structure Corrections

Cross-Reference Accuracy

Structure Enhancements

Added Missing Subsections

Improved Logical Flow

Enhanced Visual Aids

Formatting Corrections

Code Blocks

Lists

Tables

Sign-Off

Rationale