Claude-Code-Workflow/.claude/skills/software-manual/specs/writing-style.md

# Writing Style Guide

User-friendly writing standards for software manuals.

## Core Principles

### 1. User-Centered

Write for the user, not the developer.

**Do**:
- "Click the **Save** button to save your changes"
- "Enter your email address in the login form"

**Don't**:
- "The onClick handler triggers the save mutation"
- "POST to /api/auth/login with email in body"

### 2. Action-Oriented

Focus on what users can **do**, not what the system does.

**Do**:
- "You can export your data as CSV"
- "To create a new project, click **New Project**"

**Don't**:
- "The system exports data in CSV format"
- "A new project is created when the button is clicked"

### 3. Clear and Direct

Use simple, straightforward language.

**Do**:
- "Select a file to upload"
- "The maximum file size is 10MB"

**Don't**:
- "Utilize the file selection interface to designate a file for uploading"
- "File size constraints limit uploads to 10 megabytes"

## Tone

### Friendly but Professional

- Conversational but not casual
- Helpful but not condescending
- Confident but not arrogant

**Examples**:

| Too Casual | Just Right | Too Formal |
|------------|------------|------------|
| "Yo, here's how..." | "Here's how to..." | "The following procedure describes..." |
| "Easy peasy!" | "That's all you need to do." | "The procedure has been completed." |
| "Don't worry about it" | "You don't need to change this" | "This parameter does not require modification" |

### Second Person

Address the user directly as "you".

**Do**: "You can customize your dashboard..."
**Don't**: "Users can customize their dashboards..."

## Structure

### Headings

Use clear, descriptive headings that tell users what they'll learn.

**Good Headings**:
- "Getting Started"
- "Creating Your First Project"
- "Configuring Email Notifications"
- "Troubleshooting Login Issues"

**Weak Headings**:
- "Overview"
- "Step 1"
- "Settings"
- "FAQ"

### Procedures

Number steps for sequential tasks.

```markdown
## Creating a New User

1. Navigate to **Settings** > **Users**.
2. Click the **Add User** button.
3. Enter the user's email address.
4. Select a role from the dropdown.
5. Click **Save**.

The new user will receive an invitation email.
```

### Features/Options

Use bullet lists for non-sequential items.

```markdown
## Export Options

You can export your data in several formats:

- **CSV**: Compatible with spreadsheets
- **JSON**: Best for developers
- **PDF**: Ideal for sharing reports
```

### Comparisons

Use tables for comparing options.

```markdown
## Plan Comparison

| Feature | Free | Pro | Enterprise |
|---------|------|-----|------------|
| Projects | 3 | Unlimited | Unlimited |
| Storage | 1GB | 10GB | 100GB |
| Support | Community | Email | Dedicated |
```

## Content Types

### Conceptual (What Is)

Explain what something is and why it matters.

```markdown
## What is a Workspace?

A workspace is a container for your projects and team members. Each workspace
has its own settings, billing, and permissions. You might create separate
workspaces for different clients or departments.
```

### Procedural (How To)

Step-by-step instructions for completing a task.

```markdown
## How to Create a Workspace

1. Click your profile icon in the top-right corner.
2. Select **Create Workspace**.
3. Enter a name for your workspace.
4. Choose a plan (you can upgrade later).
5. Click **Create**.

Your new workspace is ready to use.
```

### Reference (API/Config)

Detailed specifications and parameters.

```markdown
## Configuration Options

### `DATABASE_URL`

- **Type**: String (required)
- **Format**: `postgresql://user:password@host:port/database`
- **Example**: `postgresql://admin:secret@localhost:5432/myapp`

Database connection string for PostgreSQL.
```

## Formatting

### Bold

Use for:
- UI elements: Click **Save**
- First use of key terms: **Workspaces** contain projects
- Emphasis: **Never** share your API key

### Italic

Use for:
- Introducing new terms: A *workspace* is...
- Placeholders: Replace *your-api-key* with...
- Emphasis (sparingly): This is *really* important

### Code

Use for:
- Commands: Run `npm install`
- File paths: Edit `config/settings.json`
- Environment variables: Set `DATABASE_URL`
- API endpoints: POST `/api/users`
- Code references: The `handleSubmit` function

### Code Blocks

Always specify the language.

```javascript
// Example: Fetching user data
const response = await fetch('/api/user');
const user = await response.json();
```

### Notes and Warnings

Use for important callouts.

```markdown
> **Note**: This feature requires a Pro plan.

> **Warning**: Deleting a workspace cannot be undone.

> **Tip**: Use keyboard shortcuts to work faster.
```

## Screenshots

### When to Include

- First time showing a UI element
- Complex interfaces
- Before/after comparisons
- Error states

### Guidelines

- Capture just the relevant area
- Use consistent dimensions
- Highlight important elements
- Add descriptive captions

```markdown
<!-- SCREENSHOT: id="ss-dashboard" description="Main dashboard showing project list" -->

*The dashboard displays all your projects with their status.*
```

## Examples

### Good Section Example

```markdown
## Inviting Team Members

You can invite colleagues to collaborate on your projects.

### To invite a team member:

1. Open **Settings** > **Team**.
2. Click **Invite Member**.
3. Enter their email address.
4. Select their role:
   - **Admin**: Full access to all settings
   - **Editor**: Can edit projects
   - **Viewer**: Read-only access
5. Click **Send Invite**.

The person will receive an email with a link to join your workspace.

> **Note**: You can have up to 5 team members on the Free plan.

<!-- SCREENSHOT: id="ss-invite-team" description="Team invitation dialog" -->
```

## Language Guidelines

### Avoid Jargon

| Technical | User-Friendly |
|-----------|---------------|
| Execute | Run |
| Terminate | Stop, End |
| Instantiate | Create |
| Invoke | Call, Use |
| Parameterize | Set, Configure |
| Persist | Save |

### Be Specific

| Vague | Specific |
|-------|----------|
| "Click the button" | "Click **Save**" |
| "Enter information" | "Enter your email address" |
| "An error occurred" | "Your password must be at least 8 characters" |
| "It takes a moment" | "This typically takes 2-3 seconds" |

### Use Active Voice

| Passive | Active |
|---------|--------|
| "The file is uploaded" | "Upload the file" |
| "Settings are saved" | "Click **Save** to keep your changes" |
| "Errors are displayed" | "The form shows any errors" |