zhongwei/gh-dhruvbaldawa-ccconfigs-essentials
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:20:33 +08:00
commit 977fbf5872
27 changed files with 5714 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

191
skills/writing-documentation/SKILL.md Normal file
View File

@@ -0,0 +1,191 @@
---
name: writing-documentation
description: Produces concise, clear documentation by applying Elements of Style principles. Use when writing or improving any technical documentation (READMEs, guides, API docs, architecture docs). Not for code comments.
---
# Writing Documentation Skill
Apply Strunk & White's *Elements of Style* principles to produce concise, clear technical documentation.
## When to Use This Skill
**Use this skill when:**
- Writing new documentation (README, API docs, guides, tutorials, architecture docs)
- Improving existing documentation
- Reviewing documentation for quality
- User asks to "make this more concise" or "improve clarity"
- User mentions: documentation, docs, README, guide, tutorial, API docs
**Do NOT use this skill for:**
- Code comments (different context, separate skill needed)
- Marketing copy (requires persuasive voice, not neutral clarity)
- Personal blog posts (requires individual voice)
## Workflows
### Workflow 1: Write New Documentation
**Steps:**
1. **Understand the purpose**
- [ ] What is the primary goal of this documentation?
- [ ] Who is the target audience?
- [ ] What do readers need to accomplish after reading?
2. **Load writing principles**
- [ ] Read `reference/strunk-white-principles.md` to internalize core principles
3. **Determine documentation type**
- [ ] Read `reference/doc-types.md` to select appropriate type
- [ ] Identify essential sections based on guidelines
4. **Draft the documentation**
- [ ] Apply Strunk & White principles while writing
5. **Validate quality**
- [ ] Run through Quality Checklist (below)
- [ ] Verify all essential information is present
- [ ] Confirm document achieves its purpose
### Workflow 2: Improve Existing Documentation
**Steps:**
1. **Read the current documentation**
- [ ] Understand its purpose and audience
- [ ] Note specific problems (verbosity, unclear sections, missing info)
2. **Load writing principles**
- [ ] Read `reference/strunk-white-principles.md`
- [ ] Review `reference/examples.md` for before/after patterns
3. **Apply improvements**
- [ ] Remove needless words
- [ ] Convert passive to active voice
- [ ] Strengthen vague statements
- [ ] Eliminate redundancy
- [ ] Improve organization if needed
4. **Validate improvements**
- [ ] Run through Quality Checklist
- [ ] Verify no information was lost
- [ ] Confirm clarity improved
### Workflow 3: Review Documentation
**Steps:**
1. **Load writing principles**
- [ ] Read `reference/strunk-white-principles.md`
- [ ] Review relevant guidelines in `reference/doc-types.md`
2. **Assess against quality criteria**
- [ ] Run through Quality Checklist (below)
- [ ] Note specific violations with examples
3. **Provide feedback**
- [ ] List specific issues found
- [ ] Reference violated principles
- [ ] Suggest concrete improvements
## Decision Framework
### When to Write vs Improve
**Write new documentation when:**
- No documentation exists
- Existing documentation is fundamentally wrong or outdated
- Complete restructuring needed (cheaper to rewrite)
**Improve existing documentation when:**
- Core structure and information are sound
- Style or clarity issues can be fixed incrementally
- Specific sections need enhancement
### Choosing Documentation Type
See `reference/doc-types.md` for detailed guidelines. Quick reference:
- **README**: Project overview, quick start, primary entry point
- **API Documentation**: Reference for function/endpoint signatures and behavior
- **Tutorial/Guide**: Step-by-step learning path for accomplishing specific goals
- **Architecture/Design Doc**: Explain system structure, decisions, and tradeoffs
- **CLI Tool Documentation**: Command reference with options and examples
### Prioritizing Conciseness vs Comprehensiveness
**Prioritize conciseness when:**
- Documentation type is reference (README, API docs, CLI docs)
- Readers need to scan quickly
- Getting started / quick start sections
**Prioritize comprehensiveness when:**
- Documentation type is learning-focused (tutorials, guides)
- Complex concepts require detailed explanation
- Architecture decisions need thorough justification
**Balance both:**
- Use concise overview sections with detailed subsections
- Link to comprehensive resources rather than embedding everything
- Apply progressive disclosure pattern
## Quality Checklist
### Content
- [ ] Purpose is clear
- [ ] Essential information is present
- [ ] No unnecessary information
- [ ] Correct and accurate
### Writing (Core Principles)
- [ ] Active voice predominates
- [ ] Definite statements (not hedging)
- [ ] Positive form
- [ ] Specific, concrete language
- [ ] Concise (no needless words)
### Structure
- [ ] Logical organization
- [ ] Clear headings
- [ ] Scannable
- [ ] Examples where helpful
### Technical Documentation
- [ ] Code examples are executable
- [ ] Commands include full context
- [ ] Prerequisites are stated
- [ ] Error cases are covered
## Reference Files
### When to Load Each Reference
**Load `reference/strunk-white-principles.md`:**
- At the start of EVERY documentation writing/improvement task
- When reviewing documentation
**Load `reference/doc-types.md`:**
- When choosing what type of documentation to write
- When unsure about essential sections for a doc type
- When reviewing documentation structure
**Load `reference/examples.md`:**
- When improving existing documentation (see patterns)
- When you want concrete before/after examples
## Common Pitfalls
**Skipping Principle Loading**: ALWAYS load `reference/strunk-white-principles.md` before writing.
**Following Guidelines Rigidly**: Adapt to the specific project's needs. Some projects don't need all sections; some need additional ones.
**Over-Editing**: "Omit needless words" means remove words that add no value. Keep all information that serves the reader's purpose.
**Sacrificing Accuracy for Brevity**: Accuracy always wins. Express explanations concisely, but never misleadingly.
**Inconsistent Terminology**: Choose one term for each concept and use it consistently.
## Notes
- This skill works iteratively - you can run it multiple times on the same document without degrading quality (idempotent)
- Quality over quantity - a short, clear document is better than a comprehensive, confusing one

354
skills/writing-documentation/reference/doc-types.md Normal file
View File

@@ -0,0 +1,354 @@
# Documentation Type Guidelines
Guidelines for different types of technical documentation. Use these principles to determine what to write and how to structure it based on your project's needs.
## Decision Framework
### Choosing Documentation Type
**What is the reader's primary goal?**
- Quick start / understand what this is → **README**
- Look up API/function signature → **API Reference**
- Learn how to accomplish a task → **Tutorial / Guide**
- Understand system design → **Architecture Documentation**
- Use a command-line tool → **CLI Documentation**
**What is the reader's experience level?**
- Newcomer to the project → README, Tutorial
- Experienced with the project → API Reference, Architecture
- Operator/deployer → Operations Guide
**What is the reader's context?**
- Evaluating whether to use this → README
- Already using, needs details → API Reference, Guide
- Debugging or troubleshooting → API Reference, Troubleshooting Guide
- Extending or modifying → Architecture Documentation
### Combining Documentation Types
**Minimal project** (small library):
- README (with inline API reference if simple)
**Standard project** (library or tool):
- README (overview, quick start)
- API Reference (detailed documentation)
- Guide (common usage patterns)
**Large project** (framework or platform):
- README (overview, links to other docs)
- Getting Started Tutorial
- API Reference (comprehensive)
- Multiple topic-specific Guides
- Architecture Documentation
- Contributing Guide
- Operations Guide
---
## README
### Purpose
Primary entry point answering: What is this? Why should I care? How do I get started?
### Target Audience
Developers evaluating whether to use your project and getting started for the first time.
### Typical Sections
**Title and Description** (required):
- Project name
- One-sentence description
- Who it's for (if not obvious)
**Installation** (required):
- Primary installation method
- Prerequisites (language version, system requirements)
- Verification step
**Quick Start** (required):
- Minimal working example
- Expected output
- Link to full documentation
**Features** (if not obvious from description):
- 3-7 main capabilities
- Distinguishing characteristics
- Key use cases
**Documentation Links** (if docs exist elsewhere):
- Getting Started Guide
- API Reference
- Advanced Usage
**License** (required for open source):
- License type
- Link to full license text
**Optional sections** (include only if they add clear value):
- Badges (build status, version, coverage)
- Contributing (how to report issues, submit changes)
- Prerequisites (if complex setup required)
- Configuration (if essential and complex)
- FAQ (if common questions exist)
### Key Guidelines
- Keep under 300 lines (preferably under 200)
- Focus on getting started quickly
- Link to detailed docs rather than embedding everything
- Use working, tested code examples
- Update as the project evolves
---
## API Reference Documentation
### Purpose
Comprehensive reference for developers using your library or API. Answers: What functions/endpoints are available? What parameters do they accept? What do they return?
### Target Audience
Developers already using your API who need to look up specific details.
### Document for Each API Element
**Signature**:
- Function/method/endpoint name
- Parameters with types
- Return type
- HTTP method and path (for REST APIs)
**Description**:
- One-sentence summary
- Additional context if needed (keep brief)
**Parameters**:
- Name, type, required/optional
- Description
- Default value (if optional)
- Constraints or valid values
**Return Value**:
- Type
- Description
- Structure (if complex)
**Errors/Exceptions**:
- Exception types thrown
- Conditions that trigger each
- HTTP status codes (for REST APIs)
**Example**:
- Minimal working example
- Common usage patterns
- Error handling (if relevant)
### Organization
**For libraries**:
- Group by module or category
- Alphabetical within groups (or by importance)
- Consistent format for each entry
**For REST APIs**:
- Group by resource
- List endpoints per resource
- Show request and response examples
### Key Guidelines
- Document every public function/endpoint
- Specify types precisely
- Include executable examples
- Document all error conditions
- Keep descriptions concise
---
## Tutorials and Guides
### Purpose
Teach readers how to accomplish specific tasks or learn concepts.
### Difference: Tutorial vs Guide
**Tutorial**:
- Step-by-step learning path
- Builds one thing from start to finish
- Assumes minimal knowledge
**Guide**:
- Explains a concept or pattern
- May skip basic steps
- Assumes familiarity with basics
### Typical Structure
**Introduction**:
- What you'll build/learn
- Why it's useful
- Estimated time (for tutorials)
- Prerequisites
**Setup**:
- Required software and versions
- Initial project setup
- Dependencies to install
**Step-by-Step Instructions**:
- What to do
- Why you're doing it (context)
- Code to add
- Expected result
- Verification/testing at each step
**Conclusion**:
- Summary of what was built/learned
- Suggestions for extending or improving
- Links to related documentation
### Key Guidelines
- Build incrementally with verification at each step
- Explain reasoning behind decisions
- Provide working, tested code
- Include troubleshooting for common issues
- Test end-to-end before publishing
---
## Architecture Documentation
### Purpose
Explain how the system is designed and why. Answers: How is the system structured? Why did we make these design decisions? What are the tradeoffs?
### Target Audience
Developers contributing to the project, teams evaluating the system, future maintainers.
### Typical Sections
**Overview**:
- What the system does
- Major components
- How components interact
**Component Details**:
- Responsibility of each component
- Key interfaces
- Dependencies
- Technology choices
**Design Decisions**:
- What decision was made
- Why it was made
- What alternatives were considered
- What tradeoffs were accepted
**Data Flow**:
- How data moves through the system
- Request/response flows
- Data transformations
**Deployment** (if relevant):
- Infrastructure components
- Scaling characteristics
- Failure modes and recovery
### Key Guidelines
- Focus on high-level structure and key decisions
- Explain tradeoffs and alternatives
- Use diagrams for complex flows
- Update as the system evolves
---
## CLI Tool Documentation
### Purpose
Help users operate command-line tools. Answers: What commands are available? What do they do? What options do they accept?
### Target Audience
Users running your command-line tool.
### Typical Sections
**Installation**:
- Installation command
- Prerequisites
- Verification step
**Basic Usage**:
- Simplest useful command
- Common patterns
- Help command
**Commands** (for each command):
- Command name and signature
- Description
- Arguments (name, description)
- Options/flags (name, description, default)
- Examples (2-3 common use cases)
**Configuration** (if applicable):
- Config file location and format
- Available options
- Precedence (env vars, config file, flags)
**Exit Codes** (for scripting):
- Exit code meanings
- When each code is returned
### Key Guidelines
- Show complete, working commands
- Include common use cases
- Document all options and flags
- Keep help text concise but complete
---
## Common Patterns Across All Types
### Progressive Disclosure
- Start with essentials
- Link to detailed information
- Don't embed everything in one document
### Examples First
- Show working example early
- Then explain details
- Examples should be executable
### Consistent Structure
- Use same format for similar elements
- Maintain parallel construction
- Keep terminology consistent
### Scannable Format
- Clear headings
- Bullet points for lists
- Code blocks for commands/examples
- Tables for structured data
### Link Between Docs
- README → Getting Started → Guides → API Reference
- Cross-reference related documentation
- Keep each doc focused on its purpose
---
## Anti-Patterns
**Don't**:
- Mix documentation types (e.g., tutorials in API reference)
- Duplicate content across multiple docs
- Include implementation details in user-facing docs
- Assume knowledge not stated in prerequisites
- Let documentation drift from reality
**Do**:
- Keep each doc type focused on its purpose
- Link to canonical information rather than duplicating
- Focus on interface, not implementation
- State all prerequisites explicitly
- Update docs when code changes

311
skills/writing-documentation/reference/examples.md Normal file
View File

@@ -0,0 +1,311 @@
# Documentation Examples: Before and After
Concrete examples of documentation improvements by applying Strunk & White principles. Each example includes annotations explaining key changes.
## Example 1: README - Project Description
### Before (73 words)
```
# MyProject
This is basically a really awesome library that we've built in order to help developers
who are working with data processing tasks. It's something that you might want to
consider using if you happen to be dealing with situations where you need to validate,
transform, or otherwise manipulate data in your applications. We think it's pretty useful
and it has been designed in such a way that it's fairly easy to use.
```
### After (17 words)
```
# MyProject
A TypeScript library for validating and transforming structured data.
Supports JSON, XML, and CSV formats with built-in validation rules.
```
### Key Changes
**Removed needless words**:
- "basically", "really awesome", "we've built", "in order to help"
- "you might want to consider using if you happen to be"
- "pretty useful", "fairly easy", "in such a way that"
**Removed hedging and qualifiers**:
- "basically", "pretty", "fairly", "might", "happen to be"
**Used definite, specific language**:
- "A TypeScript library" instead of vague description
- "Supports JSON, XML, and CSV" instead of "various different types"
- Listed capabilities directly instead of hedging
**Result**: 77% shorter while conveying all essential information.
---
## Example 2: API Documentation - Function Description
### Before (119 words)
```
### validateData()
This function is used for the purpose of validating data that has been provided by the user.
It should be noted that the function will perform various checks on the input data in order
to ensure that it meets the requirements that have been specified in the schema. In the
event that the validation process fails, an error will be returned to the calling code.
You might want to consider using this function whenever you need to make sure that user
input is valid before you process it further.
Parameters:
- data: This is the data that you want to validate
- schema: This represents the validation rules
Returns: A result object will be returned that contains information about whether the
validation succeeded or failed.
```
### After (38 words + example)
**Function signature:**
```
validateData(data, schema, options)
```
**Description:**
Validates data against a schema and returns the result.
**Parameters:**
- `data` (any): Data to validate
- `schema` (Schema): Validation rules
- `options` (ValidationOptions, optional): Configuration
**Returns:**
- `ValidationResult`: { valid: boolean, errors: array }
**Example:**
```javascript
const result = validateData(
{ email: 'user@example.com' },
{ email: 'email' }
);
```
### Key Changes
**Removed weak constructions**:
- "is used for the purpose of" → "Validates"
- "It should be noted that" → removed
- "in order to ensure" → implicit in "validates"
- "in the event that" → shown in example
- "will be returned" → "Returns"
**Removed hedging**:
- "You might want to consider" → removed (focus on what it does)
- "various checks" → removed vague description
**Added specificity**:
- Type information for all parameters
- Exact return structure
- Working code example
**Result**: More information in fewer words, scannable format.
---
## Example 3: Tutorial - Installation Section
### Before (139 words)
```
## Getting Started with Installation
Before you can actually start using MyProject, you're going to need to install it first.
The installation process is actually pretty straightforward and shouldn't take too long.
First of all, you need to make sure that you have Node.js installed on your system. If
you don't already have Node.js, you should probably go ahead and install it. You'll want
to use a relatively recent version - we'd recommend using something like version 14 or
higher, but newer versions should work fine too.
Once you've got Node.js set up and ready to go, you can then proceed to install MyProject
itself. Just open up your terminal and type in the following command:
npm install myproject
After npm finishes downloading and installing all of the necessary dependencies, you
should be all set!
```
### After (28 words)
**Section heading:**
```
## Installation
```
**Content:**
Requires Node.js 14 or later.
Install via npm:
```bash
npm install myproject
```
Verify installation:
```javascript
const myproject = require('myproject');
console.log(myproject.version);
```
### Key Changes
**Eliminated filler**:
- "Before you can actually start using", "pretty straightforward", "shouldn't take too long"
- "First of all", "Once you've got", "all set and ready"
- All explanatory preamble removed
**Removed hedging**:
- "you're going to need to", "you should probably"
- "we'd recommend something like", "should work fine too"
- "Just open up your terminal and type in"
**Made actionable**:
- Direct commands instead of instructions about commands
- Added verification step (concrete action)
- Removed obvious explanations (why you need Node.js)
**Result**: 80% shorter, faster to execute.
---
## Example 4: Architecture Documentation - Design Decision
### Before (172 words)
```
## Why We Decided to Use Message Queues
After quite a bit of discussion and consideration of various different options, we made
the decision to use message queues (specifically RabbitMQ) for communication between our
different services. This was something that we thought about pretty carefully because it's
an important architectural decision.
Basically, the main reason why we went with message queues is because they help to decouple
the services from each other. What this means is that if one service happens to go down or
become unavailable for whatever reason, it won't necessarily cause problems for the other
services. The messages will just queue up and wait.
Another thing that's nice about using message queues is that they make it easier to handle
situations where you might have sudden spikes in traffic. The queue can act as a sort of
buffer.
We did consider some alternative approaches. One option we looked at was just having the
services call each other directly using HTTP APIs, which would have been simpler in some
ways. But we ultimately felt that the benefits outweighed the added complexity.
```
### After (72 words)
**Section heading:**
```
## Design Decision: Message Queue Communication
```
**Decision**: Use RabbitMQ message queues for inter-service communication.
**Rationale**:
Services remain operational when dependencies fail. If the Processing Service crashes,
the Ingest Service continues accepting requests. Processing resumes when the service recovers.
Message queues buffer traffic spikes without overwhelming downstream services.
**Alternatives Considered**:
Direct HTTP calls:
- Simpler infrastructure (no message broker)
- Tight coupling - failures cascade
- No built-in buffering
**Tradeoffs**:
Added operational complexity (RabbitMQ cluster to maintain) and eventual consistency
(messages process asynchronously) for improved resilience.
### Key Changes
**Removed qualifiers and hedging**:
- "quite a bit of discussion", "various different options", "something that we thought about pretty carefully"
- "basically", "what this means is", "might have", "sort of"
- All process description removed
**Used active voice and structure**:
- "we made the decision" → "Decision:" header
- Organized into clear sections: Decision, Rationale, Alternatives, Tradeoffs
- Parallel construction throughout
**Made statements specific**:
- "help to decouple the services" → concrete example of decoupling
- "easier to handle situations where you might have sudden spikes" → "buffer traffic spikes"
- "simpler in some ways" → specific simplicity (infrastructure)
- "benefits outweighed the added complexity" → explicit tradeoffs listed
**Result**: 58% shorter, scannable structure, clear decision record.
---
## Common Patterns Across Examples
### Pattern 1: Remove Hedging
- Before: "You might want to consider possibly using..."
- After: "Use..."
### Pattern 2: Use Active Voice
- Before: "An error will be returned by the function..."
- After: "The function returns an error..."
### Pattern 3: Be Specific
- Before: "Use a recent version of Node.js"
- After: "Use Node.js 14 or later"
### Pattern 4: Remove Needless Words
- Before: "In order to install the package..."
- After: "To install the package..."
- Better: "Install via npm:"
### Pattern 5: Lead with Action
- Before: "If you want to process a file, you would run..."
- After: "Process a file:\n```\ncommand file\n```"
### Pattern 6: Show, Don't Tell
- Before: "The function is easy to use"
- After: [Show a simple example]
---
## Applying These Patterns
**First pass - Remove needless words**:
- Search for "in order to", "for the purpose of", "due to the fact that"
- Eliminate "basically", "actually", "really", "just", "simply"
- Remove qualifiers: "quite", "very", "rather", "somewhat"
**Second pass - Strengthen voice**:
- Convert passive to active
- Replace weak verbs (is, has, can be) with strong verbs
- Remove "there is/are" constructions
**Third pass - Increase specificity**:
- Replace vague terms with specific values
- Replace "various", "several", "some" with actual items
- Add concrete examples
**Fourth pass - Structure**:
- Use parallel construction in lists
- Lead with action
- Break long paragraphs into focused sections

674
skills/writing-documentation/reference/strunk-white-principles.md Normal file
View File

@@ -0,0 +1,674 @@
# Elements of Style - Principles for Technical Documentation
Core writing principles from Strunk & White's *Elements of Style*, adapted for technical documentation. Load this file before writing or improving any documentation.
## Summary: The 10 Core Principles
1. **Use active voice** - "The function returns X" not "X is returned"
2. **Put statements in positive form** - "Do X" not "Don't avoid X"
3. **Use definite, specific, concrete language** - Numbers, versions, exact behavior
4. **Omit needless words** - Every word must tell
5. **Express coordinate ideas in similar form** - Parallel construction
6. **Keep related words together** - Subject near verb, verb near object
7. **Choose a suitable design and hold to it** - Consistent structure
8. **Make the paragraph the unit of composition** - One topic per paragraph
9. **Avoid a succession of loose sentences** - Vary sentence structure
10. **Place emphatic words at the end** - End strong, not with qualifications
## Table of Contents
### I. Elementary Principles of Composition
- [Use the Active Voice](#use-the-active-voice)
- [Put Statements in Positive Form](#put-statements-in-positive-form)
- [Use Definite, Specific, Concrete Language](#use-definite-specific-concrete-language)
- [Omit Needless Words](#omit-needless-words)
- [Express Coordinate Ideas in Similar Form](#express-coordinate-ideas-in-similar-form)
- [Keep Related Words Together](#keep-related-words-together)
- [Choose a Suitable Design and Hold to It](#choose-a-suitable-design-and-hold-to-it)
- [Make the Paragraph the Unit of Composition](#make-the-paragraph-the-unit-of-composition)
- [Avoid a Succession of Loose Sentences](#avoid-a-succession-of-loose-sentences)
- [Place Emphatic Words at the End](#place-emphatic-words-at-the-end)
### II. Approach to Style
- [Place Yourself in the Background](#place-yourself-in-the-background)
- [Write in a Way That Comes Naturally](#write-in-a-way-that-comes-naturally)
- [Work from a Suitable Design](#work-from-a-suitable-design)
- [Write with Nouns and Verbs](#write-with-nouns-and-verbs)
- [Revise and Rewrite](#revise-and-rewrite)
- [Do Not Overwrite](#do-not-overwrite)
- [Do Not Overstate](#do-not-overstate)
- [Avoid Fancy Words](#avoid-fancy-words)
- [Be Clear](#be-clear)
- [Do Not Inject Opinion](#do-not-inject-opinion)
- [Use Figures of Speech Sparingly](#use-figures-of-speech-sparingly)
- [Avoid Foreign Languages](#avoid-foreign-languages)
- [Prefer the Standard to the Offbeat](#prefer-the-standard-to-the-offbeat)
### III. Common Patterns in Technical Writing
- [Weak Constructions to Replace](#weak-constructions-to-replace)
- [Common Qualifiers to Avoid](#common-qualifiers-to-avoid)
- [Passive Voice Patterns](#passive-voice-patterns)
- [Vague Technical Phrases](#vague-technical-phrases)
### IV. Technical Documentation Specifics
- [Code Examples](#code-examples)
- [Command Documentation](#command-documentation)
- [API Documentation](#api-documentation)
- [Error Messages](#error-messages)
---
## I. Elementary Principles of Composition
### Use the Active Voice
Active voice is direct and vigorous. Passive voice is indirect and weak.
**Pattern**: Subject performs action (active) vs subject receives action (passive)
**Bad** (passive):
```
The file is opened by the function.
An error will be returned if validation fails.
```
**Good** (active):
```
The function opens the file.
The function returns an error if validation fails.
```
**Acceptable passive** (when actor is unknown or irrelevant):
```
The data is encrypted before transmission.
The file was created in 2023.
```
---
### Put Statements in Positive Form
Make definite assertions. Avoid tame, hesitating language.
**Bad** (negative/hesitant):
```
Do not forget to set the API key.
You might want to consider using the --verbose flag.
It's not uncommon for users to encounter this error.
```
**Good** (positive/definite):
```
Set the API key before making requests.
Use the --verbose flag for detailed output.
Users commonly encounter this error.
```
---
### Use Definite, Specific, Concrete Language
Prefer the specific to the general, the definite to the vague, the concrete to the abstract.
**Bad** (vague):
```
The function runs pretty fast.
Use a recent version of Node.js.
It supports various databases.
```
**Good** (specific):
```
The function processes 10,000 records per second.
Use Node.js 18.0 or later.
It supports PostgreSQL 12+, MySQL 8+, and SQLite 3.35+.
```
---
### Omit Needless Words
Vigorous writing is concise. Every word should tell.
**Common needless phrases**:
| Wordy | Concise |
|-------|---------|
| in order to | to |
| for the purpose of | for |
| due to the fact that | because |
| at this point in time | now |
| has the ability to | can |
| make a determination | determine |
| give consideration to | consider |
| in the event that | if |
| there is/are | [restructure] |
| it is [adjective] that | [restructure] |
**Bad**:
```
In order to install the package, you will need to run the following command.
It should be noted that this function has the ability to process large files.
```
**Good**:
```
To install the package, run this command.
This function can process large files.
```
**Remove these qualifiers**: very, really, quite, rather, somewhat, fairly, pretty, basically, essentially, actually, just, simply, merely
---
### Express Coordinate Ideas in Similar Form
Parallel construction makes related ideas easier to recognize.
**Bad** (not parallel):
```
The library provides:
- Data validation
- Transforming data
- To sanitize inputs
```
**Good** (parallel):
```
The library provides:
- Data validation
- Data transformation
- Input sanitization
```
---
### Keep Related Words Together
Words that form a unit should not be separated. Keep subject near verb, verb near object.
**Bad** (separated):
```
The function, when called with invalid input, returns an error.
The user must, before sending any requests, configure the API key.
```
**Good** (together):
```
The function returns an error when called with invalid input.
The user must configure the API key before sending requests.
```
---
### Choose a Suitable Design and Hold to It
A document's organization should match its purpose. Maintain structure consistently.
**For technical documentation**:
- READMEs: Overview → Installation → Usage → Configuration
- API docs: Endpoints grouped by resource, consistent format
- Tutorials: Sequential steps, each building on previous
- Architecture docs: Context → Decision → Consequences
---
### Make the Paragraph the Unit of Composition
Each paragraph addresses a single topic. Begin with a topic sentence.
**Bad** (multiple topics):
```
This function processes user input. It also validates the data and stores it in the database.
Error handling is important because invalid data can cause crashes.
```
**Good** (one topic per paragraph):
```
This function processes user input and returns a boolean indicating success.
The function validates input before processing. Invalid data returns false immediately.
On successful validation, the function stores the data in the database.
```
---
### Avoid a Succession of Loose Sentences
Vary sentence structure. Mix short and long sentences. Use subordination to show relationships.
**Bad** (all loose):
```
Create a file. Name it config.json. Open it. Add content. Save it. Run the app.
```
**Good** (varied):
```
Create a file named config.json and add the following content. When you run the
application, it reads this config file and applies your settings.
```
---
### Place Emphatic Words at the End
The end of a sentence is the most emphatic position.
**Bad** (weak endings):
```
Run the tests before deploying, if possible.
Configure the database connection string first, typically.
```
**Good** (emphatic endings):
```
Before deploying, run the tests.
First, configure the database connection string.
```
---
## II. Approach to Style
### Place Yourself in the Background
Write in a way that draws attention to the subject matter, not the writer.
**Bad** (writer-focused):
```
I think you should use the --verbose flag.
We believe this is the right solution.
```
**Good** (subject-focused):
```
Use the --verbose flag for detailed output.
This solution addresses the core requirements.
```
---
### Write in a Way That Comes Naturally
Avoid forced or artificial language.
**Bad** (forced):
```
One must ensure that the configuration file is properly instantiated prior to
executing the application binary.
```
**Good** (natural):
```
Create and configure the config file before running the application.
```
---
### Work from a Suitable Design
Plan the structure before writing. Outline major sections to ensure logical flow.
---
### Write with Nouns and Verbs
Strong nouns and verbs carry meaning. Minimize adjectives and adverbs.
**Bad** (weak):
```
The function does validation of the input very quickly.
```
**Good** (strong):
```
The function validates the input in 10ms.
```
---
### Revise and Rewrite
First drafts are rarely optimal. Edit ruthlessly.
**Editing checklist**:
- Remove needless words
- Convert passive to active voice
- Replace vague words with specific ones
- Eliminate qualifiers
- Verify examples are executable
---
### Do Not Overwrite
Don't use ten words when five will do.
**Bad**:
```
First and foremost, it is absolutely essential to validate user input before processing.
```
**Good**:
```
Validate user input before processing.
```
---
### Do Not Overstate
Avoid hyperbole and exaggeration.
**Bad**:
```
This revolutionary approach completely solves all performance problems.
```
**Good**:
```
This approach reduces response time by 40%.
```
---
### Avoid Fancy Words
Use simple, direct language.
| Fancy | Simple |
|-------|--------|
| utilize | use |
| implement | use, add, create |
| leverage | use |
| facilitate | help, enable |
| commence | begin, start |
| terminate | end, stop |
---
### Be Clear
Clarity is the primary goal. Sacrifice everything else for clarity.
**Unclear**:
```
The function may return null if the parameter is invalid or the operation fails
depending on the configuration.
```
**Clear**:
```
The function returns null in two cases:
- The parameter is invalid
- The operation fails and config.failSafe is true
```
---
### Do Not Inject Opinion
State facts, not judgments.
**Bad** (opinion):
```
The old API was terrible and poorly designed.
```
**Good** (fact):
```
The old API required three requests to accomplish this task. The new API requires one.
```
---
### Use Figures of Speech Sparingly
Metaphors can clarify, but technical accuracy matters more.
**Appropriate**:
```
The service acts as a gatekeeper, allowing only authenticated requests.
```
**Unnecessary**:
```
The function dances through the data, gracefully extracting information.
```
---
### Avoid Foreign Languages
Use English terms when they exist.
**Appropriate** (established terms):
```
ad hoc query
de facto standard
```
**Inappropriate**:
```
Use the library vis-à-vis data processing.
```
---
### Prefer the Standard to the Offbeat
Use conventional language and structure. Avoid clever or quirky language.
---
## III. Common Patterns in Technical Writing
### Weak Constructions to Replace
**"There is/are"**:
- Bad: There are three methods available.
- Good: Three methods are available.
- Better: Use any of three methods.
**"It is"**:
- Bad: It is important to note that validation is required.
- Good: Validation is required.
**"In order to"**:
- Bad: In order to install, run npm install.
- Good: To install, run npm install.
**"Has the ability to"**:
- Bad: The function has the ability to process large files.
- Good: The function processes large files.
---
### Common Qualifiers to Avoid
Eliminate or justify each instance:
very, really, quite, rather, somewhat, fairly, pretty (as in "pretty fast"), relatively, comparatively, possibly, probably, perhaps, maybe, might, arguably, seemingly, apparently, generally, usually (unless specifying frequency), typically, basically, essentially, actually, just, simply, merely
**Bad**:
```
This is a fairly simple process.
Just run this command.
```
**Good**:
```
This is a simple process.
Run this command.
```
---
### Passive Voice Patterns
Recognize and replace:
**"Is/are/was/were [verb]ed by"**:
- Bad: The file is opened by the function.
- Good: The function opens the file.
**"Should be [verb]ed"**:
- Bad: The API key should be configured before use.
- Good: Configure the API key before use.
**"Will be [verb]ed"**:
- Bad: An error will be returned if validation fails.
- Good: The function returns an error if validation fails.
---
### Vague Technical Phrases
Replace with specific information:
**"Various", "several"**:
- Bad: Supports various databases.
- Good: Supports PostgreSQL, MySQL, and SQLite.
**"Some", "certain"**:
- Bad: Some configurations require additional setup.
- Good: Configurations with authentication require additional setup.
**"May", "might"** (when certainty exists):
- Bad: This may cause errors.
- Good: This causes 'Invalid Input' errors.
**"Appropriate", "proper"** (without defining):
- Bad: Configure the settings appropriately.
- Good: Set timeout to 30 seconds and max_retries to 3.
**"Recent", "latest"** (without version):
- Bad: Use a recent version of Node.js.
- Good: Use Node.js 18.0 or later.
**"Fast", "slow"** (without measurement):
- Bad: The function is fast.
- Good: The function processes 10,000 records per second.
---
## IV. Technical Documentation Specifics
### Code Examples
**Principles**:
- All code examples must be executable
- Show complete, working code
- Include necessary imports and setup
- Specify language for syntax highlighting
**Bad** (incomplete):
```
user = authenticate(username, password)
```
**Good** (complete):
```javascript
const { authenticate } = require('./auth');
const user = await authenticate(username, password);
if (user) {
console.log('Authentication successful');
}
```
---
### Command Documentation
**Principles**:
- Show complete commands with all flags
- Include working directory context when relevant
- Show expected output
**Bad**:
```
Run the tests.
```
**Good**:
```bash
# Run all tests
npm test
# Run specific test file
npm test -- auth.test.js
```
---
### API Documentation
**Document for each function/endpoint**:
- Signature with types
- Description (one sentence + context if needed)
- Parameters (name, type, required/optional, description)
- Return value (type, description)
- Errors/exceptions
- Example usage
**Example**:
```
validate(schema: Schema, data: unknown): ValidationResult
Validates data against a schema.
Parameters:
- schema (Schema, required): Validation rules
- data (unknown, required): Data to validate
Returns:
- ValidationResult: { valid: boolean, errors: ValidationError[] }
Throws:
- SchemaError: If schema is invalid
Example:
const result = validate(schema, { email: 'user@example.com' });
```
---
### Error Messages
**Document common errors**:
- Show actual error message
- Explain cause
- Provide concrete solution
**Example**:
```
Error: "ECONNREFUSED"
Cause: Cannot connect to database.
Solution: Verify database is running: systemctl status postgresql
```
---
## Quick Reference: Editing Passes
**First pass - Remove needless words**:
- Search for "in order to", "for the purpose of", "due to the fact that"
- Eliminate qualifiers: "quite", "very", "rather", "somewhat"
- Remove "basically", "actually", "really", "just", "simply"
**Second pass - Strengthen voice**:
- Convert passive to active
- Remove "there is/are" constructions
- Replace weak verbs (is, has, can be) with strong verbs
**Third pass - Increase specificity**:
- Replace vague terms with specific values
- Replace "various", "several" with actual items
- Add concrete examples
**Fourth pass - Structure**:
- Use parallel construction in lists
- Break long paragraphs into focused sections
- Place emphatic words at the end