Guias de estilo

local: en-US

Caso de uso: Produto SaaS B2B – Centro de Assistência e UI

# guia de estilo: EN-US – Artigos do Centro de Assistência

## 1. Propósito e Escopo

Este guia de estilo define os padrões de escrita para toda a documentação do Centro de Assistência em inglês (Estados Unidos).

Aplica-se a:

- Artigos de instruções  
- Explicações de recursos  
- Guias de solução de problemas  
- Entradas de FAQ  

**Público:** usuários profissionais de SaaS em funções técnicas e de Business  
**Objetivo:** ajudar os usuários a Concluir tarefas de forma rápida, confiante e sem confusão.

---

## 2. Voz e tom

O conteúdo do Centro de Assistência deve soar:

- **Claro e profissional**
- **Prestativo e focado em soluções**
- **Confiante, não promocional**

Escrevemos como um guia ajudando os usuários a ter sucesso — não como texto de marketing.

### Princípios de tom

| Fazer | Não fazer |
|---|------|
| Seja calmo e direto | Seja excessivamente casual ou informal |
| Foque nos passos seguintes | Foque apenas no que deu errado |
| Usar idioma Neutro | Usar sarcasmo ou humor |

**Exemplos**

- ✅ “Se a conexão falhar, verifique seu token de API e tente novamente.”  
- ❌ “Seu token está incorreto. Corrija-o.”

---

## 3. Gramática e estilo de escrita

### 3.1 Dirija-se ao leitor diretamente

Usar **você** para tornar as instruções claras.

- ✅ “Você pode gerenciar usuários a partir da página admin.”  
- ❌ “Usuários podem ser gerenciados a partir da página admin.”

---

### 3.2 Prefira a voz ativa

A voz ativa é mais curta e mais fácil de seguir.

- ✅ “Selecionar **Gravar alterações**.”  
- ❌ “Gravar alterações deve ser selecionado.”

---

### 3.3 Mantenha frases concisas

- Tente usar **25 palavras ou menos**
- Uma ideia principal por frase
- Divida explicações longas em etapas ou tópicos

---

### 3.4 Usar linguagem simples

Evite complexidade desnecessária.

- ✅ “Iniciar um novo projeto.”  
- ❌ “Iniciar a criação de um novo projeto.”

---

## 4. Terminologia e consistência

### 4.1 Usar termos Aprovado

Usar nomes de produtos e recursos exatamente como definidos.

- Manter a capitalização consistente  
- Não inventar sinônimos para conceitos chave  

**Exemplo**

- ✅ “workspace”  
- ❌ “espaço,” “área de projeto,” “ambiente”

---

### 4.2 Definir siglas incomuns

Termos comuns (API, URL) não precisam de definição.  
Siglas internas ou incomuns devem ser explicadas no primeiro usar.

- ✅ “Logon único (Logon único)”  
- ❌ “Logon único” sem contexto

---

### 4.3 Convenções do inglês dos EUA

Sempre usar a **ortografia en-US**.

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

---

## 5. Padrões de formatação e Markdown

### 5.1 Cabeçalhos

Usar cabeçalhos claros e baseados em tarefa.

- ✅ “Redefinir sua senha”  
- ❌ “Visão geral do processo de redefinição de senha”

Hierarquia de cabeçalhos:

- `#` Título do artigo  
- `##` Seções principais  
- `###` Subseções apenas quando necessário  

---

### 5.2 Listas

Usar listas numeradas para sequências:

1. Abrir **Configurações**  
2. Selecionar **Faturamento**  
3. Escolher **Alterar plano**  

Usar marcadores para opções:

- Administradores podem gerenciar usuários  
- Editores podem atualizar conteúdo  

---

### 5.3 Elementos de interface do usuário

Formatar rótulos de interface do usuário de forma consistente:

- Botões: **negrito**
- Caminhos de navegação: usar setas

Exemplo:

Vá para **Configurações → Faturamento → Alterar plano** .

---

### 5.4 Links

Links devem descrever o destino.

- ✅ “Veja o guia de faturamento”  
- ❌ “Clique aqui”

---

## 6. Estrutura de artigo padrão

Todo artigo do Centro de Assistência deve seguir esta estrutura:

### 1. Sumário

Comece com 1–2 frases explicando o resultado.

> Este artigo explica como alterar seu plano de assinatura.

---

### 2. Pré-requisitos (opcional)

Listar requisitos antecipadamente.

- Permissões de admin  
- Assinatura ativa  

---

### 3. Instruções passo a passo

As etapas devem ser:

- Orientadas à ação  
- Uma ação por etapa  
- Escritas como comandos  

Exemplo:

1. Vá para **configurações** .  
2. selecionar **Faturamento** .  
3. Escolha **alterar plano** .  

---

### 4. Resultado esperado

Diga ao usuário o que deve acontecer.

> Seu novo plano entra em vigor imediatamente após a confirmação.

---

### 5. Seguinte passos (opcional)

Forneça ações ou links relacionados.

- Gerenciar faturas  
- atualizar método de pagamento  

---

## 7. Solução de problemas e erros

### 7.1 Seja tranquilizador

- ✅ “Não conseguimos conectar. Por favor, tente novamente.”  
- ❌ “Falha na conexão. Erro crítico.”

---

### 7.2 Foque em soluções

Sempre inclua o que o usuário deve fazer a Seguinte.

- Verificar credenciais  
- Confirmar permissões  
- Contatar o suporte se necessário  

---

### 7.3 Nunca culpar o usuário

Evitar idioma como:

- “Você fez algo errado”  
- “Entrada inválida” (sem explicação)

Preferencial:

> “O token pode estar expirado. Gere um novo e tente novamente.”

---

## 8. Resumo do que fazer / não fazer

### Fazer

- Escrever conteúdo focado em tarefa e baseado em etapa  
- Usar terminologia consistente  
- Manter frases curtas e diretas  
- Usar títulos e links descritivos  
- Manter um tom calmo e de apoio  

### Não fazer

- Adicionar idioma de marketing  
- Usar expressões idiomáticas ou gírias  
- Misturar termos para o mesmo conceito  
- Culpar o usuário na solução de problemas  
- Escrever parágrafos longos sem estrutura  

---

## Exemplo (Preferencial)

Para alterar seu plano:

1. Vá para **Configurações → Faturamento**  
2. Selecionar **Alterar plano**  
3. Escolha uma opção e Selecionar **Confirmar**