Writing Documentation

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

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

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:

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:

npm install myproject

Verify installation:

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

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
• Put Statements in Positive Form
• Use Definite, Specific, Concrete Language
• Omit Needless Words
• Express Coordinate Ideas in Similar Form
• Keep Related Words Together
• Choose a Suitable Design and Hold to It
• Make the Paragraph the Unit of Composition
• Avoid a Succession of Loose Sentences
• Place Emphatic Words at the End

II. Approach to Style

• Place Yourself in the Background
• Write in a Way That Comes Naturally
• Work from a Suitable Design
• Write with Nouns and Verbs
• Revise and Rewrite
• Do Not Overwrite
• Do Not Overstate
• Avoid Fancy Words
• Be Clear
• Do Not Inject Opinion
• Use Figures of Speech Sparingly
• Avoid Foreign Languages
• Prefer the Standard to the Offbeat

III. Common Patterns in Technical Writing

• Weak Constructions to Replace
• Common Qualifiers to Avoid
• Passive Voice Patterns
• Vague Technical Phrases

IV. Technical Documentation Specifics

• Code Examples
• Command Documentation
• API Documentation
• 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:

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.

---

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):

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:

# 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