joabgonzalez 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.