technical-communication

Clear technical writing for documentation, code comments, commit messages, and architecture decisions. Emphasizes conciseness and developer-friendly communication.

When to Use

• Writing API documentation or README files
• Creating code comments and JSDoc
• Writing commit messages and PR descriptions
• Documenting architecture decisions (ADRs)
• Explaining technical concepts to team members

Don't use this skill for:

• Marketing copy or user-facing content
• Non-technical communication

---

Critical Patterns

✅ REQUIRED: Write Descriptive Commit Messages

Two formats: Simple (default) and Descriptive

Simple format (default - one line):

// ✅ CORRECT: Simple with ticket ID
[SM-14466] fix: handle API 500 error on service plan creation; add error handling for categoryIds; prevent premature Code Review

// ✅ CORRECT: Simple without ticket ID
feat: add user authentication with JWT; implement refresh tokens; include login and logout endpoints

// ❌ WRONG: Missing semicolons between summaries
[SM-123] feat: add feature update another thing do more stuff

Descriptive format (when requested):

// ✅ CORRECT: Descriptive with ticket ID
[SM-14466] fix: handle API 500 error on service plan creation

- Add error handling for 500 response when sending categoryIds
- Prevents moving ticket to Code Review if plans are not listed
- Adds explanatory comment for backend team

// ✅ CORRECT: Descriptive without ticket ID
feat: add user authentication with JWT

- Implements JWT-based authentication system
- Includes login, logout, and token refresh endpoints
- Adds session management and error handling

Rules:

• Default to simple format unless user requests "descriptive commit"
• Simple: [TICKET-ID] type: summary; summary2; summary3 (one line, semicolons separate changes)
• Descriptive: [TICKET-ID] type: summary + bullet list (one summary line + detailed changes)
• Valid types: feat, fix, refactor, chore, docs, test, etc.
• Use only ASCII apostrophes (') and hyphens (-)
• If ticket ID provided: Start with [TICKET-ID] (e.g., [SM-123], [JIRA-456])
• If NO ticket ID: Omit [TICKET-ID] entirely, start with type
• Never use placeholder [TICKET-ID] without actual ticket number

✅ REQUIRED: Use Active Voice

<!-- ✅ CORRECT: Active voice -->

The API validates the request and returns a 200 status.

<!-- ❌ WRONG: Passive voice -->

The request is validated by the API and a 200 status is returned.

✅ REQUIRED: Provide Examples

<!-- ✅ CORRECT: With example -->

## Authentication

Include your API key in the Authorization header:

\`\`\`
Authorization: Bearer your-api-key
\`\`\`

<!-- ❌ WRONG: No example -->

## Authentication

Use the Authorization header with your API key.

---

Conventions

Technical Communication Specific

• Write clear, scannable documentation
• Use active voice
• Provide context and examples
• Keep sentences concise
• Use proper markdown formatting
• Write descriptive commit messages
• Document assumptions and decisions

---

Decision Tree

API documentation?
  → Include endpoint, parameters, request/response examples, error codes

Code comment?
  → Explain "why" not "what". Avoid obvious comments

Commit message?
  → Use conventional commits format. Default: simple format ([TICKET-ID] type: summary; summary2). Use descriptive format only when user requests it ([TICKET-ID] type: summary + bullet list). Omit [TICKET-ID] if no ticket provided

README?
  → Include: purpose, installation, usage, examples, contributing guidelines

Technical decision?
  → Document with context, rationale, and impact

Complex concept?
  → Use diagrams, examples, analogies. Break into smaller sections

Error message?
  → State problem, cause, solution. Be specific and actionable

---

Example

Good commit message (simple format - default):

// With ticket ID
[SM-14466] fix: handle API 500 error on service plan creation; add error handling for categoryIds; prevent premature Code Review

// Without ticket ID
feat: add user authentication with JWT; implement refresh tokens; include login and logout endpoints

Good commit message (descriptive format - when requested):

// With ticket ID
[SM-14466] fix: handle API 500 error on service plan creation

- Add error handling for 500 response when sending categoryIds
- Prevents moving ticket to Code Review if plans are not listed
- Adds explanatory comment for backend team

// Without ticket ID
feat: add user authentication with JWT

- Implements JWT-based authentication system
- Includes login, logout, and token refresh endpoints
- Adds session management and error handling

Good documentation:

## Authentication

The API uses JWT tokens for authentication. Include the token in the Authorization header:

\`\`\`
Authorization: Bearer <token>
\`\`\`

Tokens expire after 1 hour. Use the refresh endpoint to obtain a new token.

---

Edge Cases

Audience knowledge level: Adjust technical depth based on audience. Avoid jargon for general audience.

Outdated documentation: Review and update docs regularly. Use doc tests or CI checks.

Version-specific docs: Clearly indicate which version documentation applies to.

Non-native English speakers: Use simple, clear language. Avoid idioms and complex sentences.

Code examples: Ensure examples are runnable and tested. Include necessary imports and setup.

---

Resources

• https://www.writethedocs.org/guide/writing/style-guides/
• https://developers.google.com/style