// Analyze technical documentation for clarity, conciseness, and effectiveness using Google Technical Writing principles. Use when reviewing documentation, checking writing quality, improving docs, or providing writing feedback.
[HINT] 下载包含 SKILL.md 和所有相关文件的完整技能目录
| name | linting-technical-writing |
| description | Analyze technical documentation for clarity, conciseness, and effectiveness using Google Technical Writing principles. Use when reviewing documentation, checking writing quality, improving docs, or providing writing feedback. |
Apply Google's Technical Writing principles to analyze and improve documentation.
Check for undefined terms:
❌ BAD: "The REST API provides..."
✅ GOOD: "The REST (Representational State Transfer) API provides..."
Verify consistent terminology:
❌ BAD: Mix "API endpoint", "URL", "API route", "path"
✅ GOOD: Always use "API endpoint"
Acronym usage:
❌ BAD: "Use JWT for authentication"
✅ GOOD: "Use JWT (JSON Web Token) for authentication"
Pronoun clarity:
❌ BAD: "When the server receives the request, it processes it."
(Which "it"? Server or request?)
✅ GOOD: "When the server receives the request, the server processes the request."
Identify passive voice:
❌ PASSIVE: "The configuration file is loaded by the system."
✅ ACTIVE: "The system loads the configuration file."
❌ PASSIVE: "Errors are handled by the middleware."
✅ ACTIVE: "The middleware handles errors."
Weak verbs:
❌ WEAK: "There is a function that validates input."
✅ STRONG: "The validateInput function validates input."
❌ WEAK: "The error occurs when the timeout is exceeded."
✅ STRONG: "The request times out after 30 seconds."
Subjective adjectives:
❌ VAGUE: "The API is blazingly fast."
✅ SPECIFIC: "The API responds in under 100ms for 95% of requests."
❌ VAGUE: "Simply install the package."
✅ CLEAR: "Install the package with npm install package-name."
Long sentences:
❌ TOO LONG (45 words):
"The API endpoint accepts JSON payloads that contain user data including name, email, address, phone number, and optional preferences which are then processed by the backend service and stored in the database after validation."
✅ BETTER (split into 3 sentences):
"The API endpoint accepts JSON payloads containing user data. Required fields include name, email, address, and phone number. Optional preferences can also be included."
Parallel structure:
❌ NOT PARALLEL:
* Create a new file
* The user should configure settings
* Restart the server
✅ PARALLEL:
* Create a new file
* Configure settings
* Restart the server
List introduction:
❌ NO INTRODUCTION:
* Item 1
* Item 2
✅ WITH INTRODUCTION:
Follow these steps:
* Item 1
* Item 2
Numbered vs bulleted:
✅ NUMBERED (sequential):
1. Install dependencies
1. Configure the application
1. Start the server
✅ BULLETED (unordered):
* Supports JSON format
* Handles authentication
* Includes error logging
Opening sentences:
❌ WEAK OPENING:
"There are several things to consider. Authentication is important..."
✅ STRONG OPENING:
"Authentication protects your API from unauthorized access."
Single focus:
❌ MULTIPLE TOPICS:
"The API uses JWT tokens for authentication. The database stores user data in PostgreSQL. Error messages follow RFC 7807 format."
✅ SINGLE TOPIC:
"The API uses JWT tokens for authentication. Tokens expire after 24 hours. Refresh tokens using the /auth/refresh endpoint."
Paragraph length:
Define prerequisites:
❌ ASSUMES KNOWLEDGE:
"Configure your ingress controller."
✅ STATES PREREQUISITES:
"**Prerequisites**: Basic Kubernetes knowledge and kubectl installed.
Configure your ingress controller:"
Avoid idioms:
❌ CULTURAL IDIOM: "This feature is the bee's knees."
✅ CLEAR: "This feature significantly improves performance."
Scope definition:
## What This Guide Covers
This guide explains how to:
* Install the application
* Configure basic settings
* Deploy to production
This guide does NOT cover:
* Advanced customization
* Troubleshooting
* Performance tuning
Audience declaration:
## Who This Is For
**Target audience**: Backend developers familiar with Node.js
**Prerequisites**:
* Node.js 18+ installed
* Basic understanding of REST APIs
* Command line experience
# Technical Writing Lint Report
## Summary
- Total issues: 23
- High severity: 3
- Medium severity: 15
- Low severity: 5
## High Severity Issues
### 1. Undefined Technical Term (Line 8)
**Issue**: Term "REST" used without definition
**Current**: "The REST API provides..."
**Suggested**: "The REST (Representational State Transfer) API provides..."
## Medium Severity Issues
### Category: Passive Voice (8 issues)
**Line 15:**
**Current**: "The configuration file is loaded by the system."
**Suggested**: "The system loads the configuration file."
**Line 22:**
**Current**: "Errors are handled by the middleware."
**Suggested**: "The middleware handles errors."
### Category: Long Sentences (4 issues)
**Line 45 (62 words):**
**Current**: "The API endpoint accepts JSON payloads that contain user data including name, email, address, phone number, and optional preferences which are processed by the backend service and stored in the database after validation completes successfully."
**Suggested**:
"The API endpoint accepts JSON payloads containing user data. Required fields include name, email, address, and phone number. Optional preferences can also be included. The backend validates and stores all data."
These changes can be applied automatically: