evolution-foundation /cs-kb-article
Se encontrar integrações não configuradas, verifique 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:
- Título: Claro, pesquisável, descreve o resultado ou problema (não jargão interno)
- Overview: 1-2 frases explicando o que o artigo cobre e para quem é
- Corpo: Conteúdo estruturado adequado ao tipo de artigo
- Artigos relacionados: Links para conteúdo complementar relevante
- 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
- Rascunho: Escrito, precisa de revisão
- Publicado: Ativo e disponível para clientes
- Precisa de atualização: Sinalizado para revisão (mudança de produto, feedback ou idade)
- Arquivado: Não mais relevante mas preservado para referência
- 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
- Escrever para o cliente que está frustrado e buscando uma resposta — ser claro, direto e útil
- Todo artigo deve ser encontrável através de busca usando as palavras que um cliente digitaria
- Testar seus artigos — seguir os passos você mesmo ou pedir a alguém não familiarizado com o tópico para segui-los
- Manter artigos focados — um problema, uma solução. Dividir se um artigo estiver crescendo demais
- Manter agressivamente — um artigo errado é pior que nenhum artigo
- Rastrear o que está faltando — todo ticket que poderia ter sido um artigo KB é um gap de conteúdo
- Medir impacto — artigos que não recebem tráfego ou não reduzem tickets precisam ser melhorados ou retirados