technical-writing

# Technical Writing Skill

Standards and best practices for technical writing.

## Writing Principles

### Clarity

```markdown
## Be Clear

❌ "Utilize the aforementioned methodology to facilitate optimal outcomes."

✅ "Use this method to get the best results."

## Rules:
- Use simple words
- One idea per sentence
- Active voice over passive
- Specific over vague
```

### Conciseness

```markdown
## Be Concise

❌ "In order to effectively and efficiently process the data,
    it is necessary that the system must first initialize."

✅ "The system must initialize before processing data."

## Cut:
- Unnecessary words ("very", "really", "actually")
- Redundant phrases ("end result", "future plans")
- Filler phrases ("it should be noted that")
```

### Consistency

```markdown
## Be Consistent

### Terminology
Pick one term and stick with it:
- "user" or "customer" (not both)
- "click" or "select" (not both)
- "app" or "application" (not both)

### Formatting
- Code: `backticks`
- UI elements: **bold**
- File paths: `code`
- First mention of terms: *italics*
```

## Style Guide

### Voice and Tone

```markdown
## Voice Characteristics

### Professional but Friendly
❌ "One must ensure that..."
✅ "Make sure you..."

❌ "Heyyy! Super excited to show you..."
✅ "We're excited to introduce..."

### Direct and Helpful
❌ "You might want to consider..."
✅ "We recommend..."

❌ "There are several ways to..."
✅ "Do this by..."
```

### Sentence Structure

```markdown
## Sentence Guidelines

### Lead with Action
❌ "To create a new user, click the Create button."
✅ "Click Create to add a new user."

### One Action per Step
❌ "Click Settings, then Security, then API Keys."
✅ "1. Click Settings
    2. Select Security
    3. Click API Keys"

### Front-Load Key Information
❌ "If you're using Docker, skip this step."
✅ "Skip this step if you're using Docker."
```

### Technical Terms

```markdown
## Handling Technical Terms

### Define on First Use
"The API uses *webhooks* (HTTP callbacks tr