cs-kb-article

/cs-kb-article

Se encontrar integrações não configuradas, verifique [CONNECTORS.md](../../CONNECTORS.md).

Redigir um artigo de base de conhecimento pronto para publicação a partir de um problema de suporte resolvido, pergunta frequente ou workaround documentado. Estrutura o conteúdo para pesquisabilidade e self-service.

Usage

/cs-kb-article <problema resolvido, referência de ticket ou descrição do tópico>

Exemplos:

• /cs-kb-article Como configurar SSO com Okta — resolvi isso para 3 clientes no mês passado
• /cs-kb-article Ticket #4521 — cliente não conseguia exportar dados com mais de 10k linhas
• /cs-kb-article Pergunta frequente: como configurar notificações via webhook
• /cs-kb-article Problema conhecido: gráficos do dashboard não carregam no Safari 16

Workflow

1. Entender o Material Fonte

Analisar o input para identificar:

• Qual foi o problema? O problema original, pergunta ou erro
• Qual foi a solução? A resolução, workaround ou resposta
• Quem é afetado? Tipo de usuário, nível de plano ou configuração
• Qual é a frequência? Problema único ou recorrente
• Qual tipo de artigo se encaixa melhor? How-to, troubleshooting, FAQ, problema conhecido ou referência (ver tipos de artigo abaixo)

Se uma referência de ticket for fornecida, buscar o contexto completo:

• int-evo-crm (/int-evo-crm): Puxar o thread do ticket, resolução e quaisquer notas internas
• Notion MCP: Verificar se um artigo similar já existe (atualizar vs. criar novo)
• int-linear-review (/int-linear-review) ou Linear MCP: Verificar se há bug report ou feature request relacionado

2. Redigir o Artigo

Usando a estrutura de artigo, padrões de formatação e boas práticas de pesquisabilidade abaixo:

• Seguir o template para o tipo de artigo escolhido (how-to, troubleshooting, FAQ, problema conhecido ou referência)
• Aplicar as boas práticas de pesquisabilidade: título em linguagem do cliente, frase de abertura em linguagem simples, mensagens de erro exatas, sinônimos comuns
• Manter escaneável: headers, passos numerados, parágrafos curtos

3. Gerar o Artigo

Apresentar o rascunho com metadados:

## Rascunho de Artigo KB

**Título:** [Título do artigo]
**Tipo:** [How-to / Troubleshooting / FAQ / Problema Conhecido / Referência]
**Categoria:** [Área de produto ou tópico]
**Tags:** [Tags pesquisáveis]
**Público:** [Todos os usuários / Admins / Desenvolvedores / Plano específico]

---

[Conteúdo completo do artigo — usando o template apropriado abaixo]

---

### Notas de Publicação
- **Fonte:** [Ticket #, conversa com cliente, ou discussão interna]
- **Artigos existentes para atualizar:** [Se isso tem sobreposição com conteúdo existente]
- **Revisão necessária de:** [SME ou time se precisar verificar precisão técnica]
- **Data de revisão sugerida:** [Quando revisitar para verificar precisão]

4. Oferecer Próximos Passos

Após gerar o artigo:

• "Quer que eu verifique se um artigo similar já existe no Notion?"
• "Devo ajustar a profundidade técnica para um público diferente?"
• "Quer que eu redija um artigo complementar (ex: um how-to para acompanhar este guia de troubleshooting)?"
• "Devo criar uma versão apenas interna com detalhes técnicos adicionais?"

Estrutura de Artigo e Padrões de Formatação

Elementos Universais de Artigo

Todo artigo KB deve incluir:

1. Título: Claro, pesquisável, descreve o resultado ou problema (não jargão interno)
2. Overview: 1-2 frases explicando o que o artigo cobre e para quem é
3. Corpo: Conteúdo estruturado adequado ao tipo de artigo
4. Artigos relacionados: Links para conteúdo complementar relevante
5. Metadados: Categoria, tags, público, data da última atualização

Regras de Formatação

• Usar headers (H2, H3) para dividir o conteúdo em seções escaneáveis
• Usar listas numeradas para passos sequenciais
• Usar listas de bullets para itens não sequenciais
• Usar negrito para nomes de elementos de UI, termos-chave e ênfase
• Usar blocos de código para comandos, chamadas de API, mensagens de erro e valores de configuração
• Usar tabelas para comparações, opções ou dados de referência
• Usar callouts/notas para avisos, dicas e ressalvas importantes
• Manter parágrafos curtos — 2-4 frases no máximo
• Uma ideia por seção — se uma seção cobre dois tópicos, dividir

Escrevendo para Pesquisabilidade

Artigos são inúteis se os clientes não conseguem encontrá-los. Otimizar cada artigo para busca:

Boas Práticas de Título

| Bom Título | Título Ruim | Por quê | |------------|-----------|-----| | "Como configurar SSO com Okta" | "Configuração SSO" | Específico, inclui o nome da ferramenta que clientes buscam | | "Fix: Dashboard mostra página em branco" | "Problema no Dashboard" | Inclui o sintoma que os clientes vivenciam | | "Rate limits e quotas da API" | "Informações da API" | Inclui os termos específicos que clientes buscam | | "Erro: 'Connection refused' ao importar dados" | "Problemas de Importação" | Inclui a mensagem de erro exata |

Otimização de Palavras-Chave

• Incluir mensagens de erro exatas — clientes copiam e colam texto de erro na busca
• Usar linguagem do cliente, não terminologia interna — "não consigo fazer login" não "falha de autenticação"
• Incluir sinônimos comuns — "deletar/remover", "dashboard/página inicial", "exportar/baixar"
• Adicionar fraseamentos alternativos — abordar o mesmo problema de ângulos diferentes no overview
• Taguear por áreas de produto — garantir que categoria e tags correspondam à forma como clientes pensam sobre o produto

Fórmula de Frase de Abertura

Começar cada artigo com uma frase que recoloca o problema ou tarefa em linguagem simples:

• How-to: "Este guia mostra como [realizar X]."
• Troubleshooting: "Se você estiver vendo [sintoma], este artigo explica como corrigir."
• FAQ: "[Pergunta nas palavras do cliente]? Aqui está a resposta."
• Problema conhecido: "Alguns usuários estão vivenciando [sintoma]. Aqui está o que sabemos e como contornar."

Templates por Tipo de Artigo

Artigos How-to

Objetivo: Instruções passo a passo para realizar uma tarefa.

Estrutura:

# Como [realizar tarefa]

[Overview — o que este guia cobre e quando usá-lo]

## Pré-requisitos
- [O que é necessário antes de começar]

## Passos
### 1. [Ação]
[Instrução com detalhes específicos]

### 2. [Ação]
[Instrução]

## Verificar se Funcionou
[Como confirmar o sucesso]

## Problemas Comuns
- [Problema]: [Solução]

## Artigos Relacionados
- [Links]

Boas práticas:

• Começar cada passo com um verbo
• Incluir o caminho específico: "Vá em Configurações > Integrações > Chaves de API"
• Mencionar o que o usuário deve ver após cada passo ("Você deve ver um banner verde de confirmação")
• Testar os passos você mesmo ou verificar com uma resolução recente de ticket

Artigos de Troubleshooting

Objetivo: Diagnosticar e resolver um problema específico.

Estrutura:

# [Descrição do problema — o que o usuário vê]

## Sintomas
- [O que o usuário observa]

## Causa
[Por que isso acontece — explicação breve e sem jargão]

## Solução
### Opção 1: [Correção principal]
[Passos]

### Opção 2: [Alternativa se a Opção 1 não funcionar]
[Passos]

## Prevenção
[Como evitar isso no futuro]

## Ainda Com Problemas?
[Como obter ajuda]

Boas práticas:

• Começar com sintomas, não causas — clientes buscam pelo que veem
• Fornecer múltiplas soluções quando possível (correção mais provável primeiro)
• Incluir uma seção "Ainda com problemas?" que aponta para o suporte
• Se a causa raiz for complexa, manter a explicação voltada ao cliente simples

Artigos FAQ

Objetivo: Resposta rápida a uma pergunta comum.

Estrutura:

# [Pergunta — nas palavras do cliente]

[Resposta direta — 1-3 frases]

## Detalhes
[Contexto adicional, nuances ou explicação se necessário]

## Perguntas Relacionadas
- [Link para FAQ relacionado]
- [Link para FAQ relacionado]

Boas práticas:

• Responder a pergunta na primeira frase
• Manter conciso — se a resposta precisa de um passo a passo, é um how-to, não um FAQ
• Agrupar FAQs relacionados e criar links entre eles

Artigos de Problema Conhecido

Objetivo: Documentar um bug conhecido ou limitação com um workaround.

Estrutura:

# [Problema Conhecido]: [Descrição breve]

**Status:** [Investigando / Workaround Disponível / Correção em Progresso / Resolvido]
**Afetados:** [Quem/o que é afetado]
**Última atualização:** [Data]

## Sintomas
[O que os usuários vivenciam]

## Workaround
[Passos para contornar o problema, ou "Nenhum workaround disponível"]

## Prazo de Correção
[Data prevista de correção ou status atual]

## Atualizações
- [Data]: [Atualização]

Boas práticas:

• Manter o status atualizado — nada corrói a confiança mais rápido do que um artigo de problema conhecido desatualizado
• Atualizar o artigo quando a correção for lançada e marcar como resolvido
• Se resolvido, manter o artigo ativo por 30 dias para clientes ainda buscando os sintomas antigos

Cadência de Revisão e Manutenção

Bases de conhecimento decaem sem manutenção. Seguir esse cronograma:

| Atividade | Frequência | Quem | |----------|-----------|-----| | Revisão de novo artigo | Antes de publicar | Revisão de par + SME para conteúdo técnico | | Auditoria de precisão | Trimestral | Time de suporte revisa artigos de maior tráfego | | Verificação de conteúdo obsoleto | Mensal | Sinalizar artigos não atualizados em 6+ meses | | Atualizações de problemas conhecidos | Semanal | Atualizar status em todos os problemas conhecidos abertos | | Revisão de analytics | Mensal | Verificar quais artigos têm baixas avaliações de utilidade ou altas taxas de rejeição | | Análise de gaps | Trimestral | Identificar principais tópicos de tickets sem artigos KB |

Ciclo de Vida do Artigo

1. Rascunho: Escrito, precisa de revisão
2. Publicado: Ativo e disponível para clientes
3. Precisa de atualização: Sinalizado para revisão (mudança de produto, feedback ou idade)
4. Arquivado: Não mais relevante mas preservado para referência
5. Retirado: Removido da base de conhecimento

Quando Atualizar vs. Criar Novo

Atualizar existente quando:

• O produto mudou e os passos precisam ser atualizados
• O artigo está majoritariamente correto mas falta um detalhe
• Feedback indica que clientes estão confusos com uma seção específica
• Um workaround ou solução melhor foi encontrado

Criar novo quando:

• Uma nova feature ou área de produto precisa de documentação
• Um ticket resolvido revela um gap — nenhum artigo existe para esse tópico
• O artigo existente cobre muitos tópicos e deve ser dividido
• Um público diferente precisa da mesma informação explicada de forma diferente

Taxonomia de Links e Categorização

Estrutura de Categorias

Organizar artigos em uma hierarquia que corresponde à forma como os clientes pensam:

Primeiros Passos
├── Configuração de conta
├── Configuração inicial
└── Guias de início rápido

Features e How-tos
├── [Área de feature 1]
├── [Área de feature 2]
└── [Área de feature 3]

Integrações
├── [Integração 1]
├── [Integração 2]
└── Referência de API

Troubleshooting
├── Erros comuns
├── Problemas de performance
└── Problemas conhecidos

Billing e Conta
├── Planos e preços
├── Dúvidas de billing
└── Gerenciamento de conta

Boas Práticas de Links

• Link de troubleshooting para how-to: "Para instruções de configuração, veja [Como configurar X]"
• Link de how-to para troubleshooting: "Se encontrar erros, veja [Troubleshooting X]"
• Link de FAQ para artigos detalhados: "Para um passo a passo completo, veja [Guia de X]"
• Link de problemas conhecidos para workarounds: Manter a cadeia do problema para a solução curta
• Usar links relativos dentro do KB — sobrevivem melhor a reestruturações do que URLs absolutas
• Evitar links circulares — se A linka para B, B não deve linkar de volta para A a menos que ambos sejam pontos de entrada genuinamente úteis

Boas Práticas de Escrita KB

1. Escrever para o cliente que está frustrado e buscando uma resposta — ser claro, direto e útil
2. Todo artigo deve ser encontrável através de busca usando as palavras que um cliente digitaria
3. Testar seus artigos — seguir os passos você mesmo ou pedir a alguém não familiarizado com o tópico para segui-los
4. Manter artigos focados — um problema, uma solução. Dividir se um artigo estiver crescendo demais
5. Manter agressivamente — um artigo errado é pior que nenhum artigo
6. Rastrear o que está faltando — todo ticket que poderia ter sido um artigo KB é um gap de conteúdo
7. Medir impacto — artigos que não recebem tráfego ou não reduzem tickets precisam ser melhorados ou retirados