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.

## 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.

## 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.

## 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.

## 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.

## 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.

## 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.

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

Notes and Warnings

Use for important callouts.

> **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

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

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

Examples

Good Section Example

## 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"