Guias de estilo

Locale: en-US

Use case: SaaS B2B Product – Help Center and UI

# Style Guide: EN-US – Help Center Articles

## 1. Purpose & Scope

This style guide defines the writing standards for all **Help Center documentation** in **English (United States)**.

It applies to:

- How-to articles  
- Feature explanations  
- Troubleshooting guides  
- FAQ entries  

**Audience:** professional SaaS users in technical and business roles  
**Goal:** help users complete tasks quickly, confidently, and without confusion.

---

## 2. Voice & Tone

Help Center content should sound:

- **Clear and professional**
- **Supportive and solution-focused**
- **Confident, not promotional**

We write as a guide helping users succeed — not as marketing copy.

### Tone principles

| Do | Don’t |
|---|------|
| Be calm and direct | Be overly casual or chatty |
| Focus on next steps | Focus only on what went wrong |
| Use neutral language | Use sarcasm or humor |

**Examples**

- ✅ “If the connection fails, check your API token and try again.”  
- ❌ “Your token is wrong. Fix it.”

---

## 3. Grammar & Writing Style

### 3.1 Address the reader directly

Use **you** to make instructions clear.

- ✅ “You can manage users from the Admin page.”  
- ❌ “Users can be managed from the Admin page.”

---

### 3.2 Prefer active voice

Active voice is shorter and easier to follow.

- ✅ “Select **Save changes**.”  
- ❌ “Save changes should be selected.”

---

### 3.3 Keep sentences concise

- Aim for **25 words or fewer**
- One main idea per sentence
- Break long explanations into steps or bullets

---

### 3.4 Use plain language

Avoid unnecessary complexity.

- ✅ “Start a new project.”  
- ❌ “Initiate the creation of a new project.”

---

## 4. Terminology & Consistency

### 4.1 Use approved terms

Use product and feature names exactly as defined.

- Keep capitalization consistent  
- Do not invent synonyms for key concepts  

**Example**

- ✅ “workspace”  
- ❌ “space,” “project area,” “environment”

---

### 4.2 Define uncommon acronyms

Common terms (API, URL) do not need definition.  
Internal or uncommon acronyms should be explained on first use.

- ✅ “Single Sign-On (SSO)”  
- ❌ “SSO” without context

---

### 4.3 US English conventions

Always use **en-US spelling**.

- ✅ “customize,” “behavior”  
- ❌ “customise,” “behaviour”

---

## 5. Formatting & Markdown Standards

### 5.1 Headings

Use clear, task-based headings.

- ✅ “Reset your password”  
- ❌ “Password resetting process overview”

Heading hierarchy:

- `#` Article title  
- `##` Main sections  
- `###` Subsections only when needed  

---

### 5.2 Lists

Use numbered lists for sequences:

1. Open **Settings**  
2. Select **Billing**  
3. Choose **Change plan**  

Use bullets for options:

- Admins can manage users  
- Editors can update content  

---

### 5.3 UI elements

Format UI labels consistently:

- Buttons: **bold**
- Navigation paths: use arrows

Exemplo:

Go to **Settings → Billing → Change plan**.

---

### 5.4 Links

Links must describe the destination.

- ✅ “See the billing guide”  
- ❌ “Click here”

---

## 6. Standard Article Structure

Every Help Center article should follow this structure:

### 1. Summary

Start with 1–2 sentences explaining the outcome.

> This article explains how to change your subscription plan.

---

### 2. Prerequisites (optional)

List requirements upfront.

- Admin permissions  
- Active subscription  

---

### 3. Step-by-step instructions

Steps should be:

- Action-oriented  
- One action per step  
- Written as commands  

Exemplo:

1. Go to **Settings**.  
2. Select **Billing**.  
3. Choose **Change plan**.  

---

### 4. Expected result

Tell the user what should happen.

> Your new plan takes effect immediately after confirmation.

---

### 5. Next steps (optional)

Provide related actions or links.

- Manage invoices  
- Update payment method  

---

## 7. Troubleshooting & Errors

### 7.1 Be reassuring

- ✅ “We couldn’t connect. Please try again.”  
- ❌ “Connection failed. Critical error.”

---

### 7.2 Focus on solutions

Always include what the user should do next.

- Check credentials  
- Confirm permissions  
- Contact support if needed  

---

### 7.3 Never blame the user

Avoid language like:

- “You did something wrong”  
- “Invalid input” (without explanation)

Preferred:

> “The token may be expired. Generate a new one and retry.”

---

## 8. Do / Don’t Summary

### Do

- Write task-focused, step-based content  
- Use consistent terminology  
- Keep sentences short and direct  
- Use descriptive headings and links  
- Maintain a calm, supportive tone  

### Don’t

- Add marketing language  
- Use idioms or slang  
- Mix terms for the same concept  
- Blame the user in troubleshooting  
- Write long paragraphs without structure  

---

## Example (Preferred)

To change your plan:

1. Go to **Settings → Billing**  
2. Select **Change plan**  
3. Choose an option and select **Confirm**