¶ Knowledge Base Govendas/Gogeo
Bem-vindos ao centro de conhecimento técnico da Govendas/Gogeo
Este é o repositório oficial de documentação, procedimentos e conhecimento técnico do nosso time interno.
Atenção
É muito importante ler esta página por completo.
Este Knowledge Base foi criado para centralizar todo o conhecimento técnico da Govendas e Gogeo, facilitando o compartilhamento de informações, procedimentos operacionais e soluções entre nossos times de desenvolvimento, infraestrutura e operações.
Objetivos principais:
- Documentar procedimentos e processos críticos
- Compartilhar soluções técnicas testadas
- Facilitar onboarding de novos membros
- Manter histórico de decisões arquiteturais
- Criar base de conhecimento para troubleshooting
Wiki.js é uma plataforma moderna de documentação que oferece:
- Editores múltiplos: Markdown, Visual (WYSIWYG), e HTML
- Versionamento automático: Histórico completo de mudanças
- Busca avançada: Encontre informações rapidamente
- Colaboração: Edição em tempo real e comentários
- Backup automático: Sincronização com Git
- Acesso controlado: Permissões por usuário e grupo
Por que escolhemos Wiki.js:
- Interface moderna e intuitiva
- Suporte nativo ao Markdown
- Integração com nossos sistemas existentes
- Performance superior para grandes volumes de documentação
Abaixo segue a estrutura idealizada para formação da base de conhecimento. Ela pode ser alterada a medida que novos entendimentos forem sendo formados. A estrutura "em tempo real" deste repositório está aqui: https://kb.govendas.com/a/pages/visualize.
Orientações para criar novos usuários
Novos usuários devem ser cadastrados por um usuário Gestor ou Administrador.
- Crie um usuário utilizando o email do govendas
- Ao criar um novo usuário marque para redefinir senha
- Faça a associação aos grupos do usuário (Gestor, Colaborador, times, ...)
- Envie para o email do usuário a senha provisória criada
- Envie junto com a senha a seguinte mensagem:
Ao iniciar os trabalhos na Wiki, leia atentamente a página Home. Ela ira explicar detalhes importantes de como utilizar a wiki.
Temos 3 tipos de usuários básicos:
- Colaborador
Consegue fazer a edição de conteúdo
- Gestor
Consegue fazer a gestão de usuários, edição de conteúdo, gerenciamento de comentários, gestão de navegação, criação de novos grupos de usuários.
- Administrador
Consegue fazer a gestão de usuários, edição de conteúdo, gerenciamento de comentários, gestão de navegação, criação de novos grupos de usuários, gerenciamento de API, definição de templates, definição de temas, configurações gerais.
Há grupos adicionais para os times do goVendas. Eles são úteis para organizar os recursos de navegação, otimizando os interesses de cada time.
Um recurso muito importante do Wiki.js é a organização da navegação.
Este recurso pode ser configurado pelos usuários Gestor e permite que se customizem páginas com uma navegabilidade útil para o time, correlacionando páginas de maior interesse e importância.
Para acessar as configurações da navegabilidade utilize o menu de configuração e depois navegação.
Durante a configuração da navegação é muito importante atribuir as configurações de navegabilidade aos grupos dos seus times. Assim, os usuários de cada time terão uma visão diferente que atendem seus interesses, segundo a visão do gestor.
Clarity First (Clareza em Primeiro Lugar)
Escreva como se estivesse explicando para um colega que vai implementar o procedimento pela primeira vez.
1. Seja Específico e Detalhado
- Use comandos exatos e exemplos reais
- Inclua outputs esperados
- Documente pré-requisitos e dependências
- Especifique versões de software quando relevante
2. Mantenha Atualizado
- Revise documentação regularmente
- Atualize após mudanças nos sistemas
- Remova informações obsoletas
- Use datas nas documentações críticas
3. Use Exemplos Práticos
- Prefira exemplos reais do nosso ambiente
- Inclua casos de erro comuns
- Documente troubleshooting steps
- Adicione screenshots quando necessário
Para procedimentos técnicos, use esta estrutura:
# Título Descritivo
## Visão Geral
- O que este procedimento faz
- Quando usar
- Tempo estimado
## Pré-requisitos
- Acessos necessários
- Ferramentas requeridas
- Conhecimento prévio
## Procedimento Passo-a-Passo
1. Comando/ação específica
2. Resultado esperado
3. Validação
## Troubleshooting
- Problemas comuns
- Como identificar
- Como resolver
## Validação
- Como verificar se funcionou
- Comandos de teste
- Métricas de sucesso
Use os recursos visuais do Wiki.js:
Informações importantes
Use blockquotes azuis para dicas e informações gerais{.is-info}
Avisos de cuidado
Use blockquotes laranjas para procedimentos que requerem atenção{.is-warning}
Alertas críticos
Use blockquotes vermelhos para operações perigosas ou críticas{.is-danger}
Resultados positivos
Use blockquotes verdes para indicar sucesso ou boas práticas{.is-success}
Organize conteúdo com tabsets:
## Seção Principal {.tabset}
### Aba 1
Conteúdo da primeira aba
### Aba 2
Conteúdo da segunda aba
Convenções de nomenclatura:
- Títulos em português, descritivos e específicos
- Use hierarquia clara (H1 > H2 > H3)
- Prefixe páginas por categoria:
[Infra],[Dev],[Proc] - Use datas em procedimentos temporais:
2025-01-15
Organização de páginas:
- Crie estrutura de pastas lógica
- Use tags consistentes
- Mantenha índices atualizados
- Cross-reference páginas relacionadas
Clique no ícone no canto superior direito para criar uma nova página. Defina um caminho de diretórios de acordo com a estrutura dos documentos apresentados na sessão Estrutura do KB.
Se necessário faça uma redefinição da estrutura, não esqueça de atualizar o gráfico.
Para editar, utilize o menu no canto superior direito:
Se quizer alterar a estrutura dos documentos ou mesmo renomeá-los, utilize o menu no canto superior direito.
A estrutura é definida somente pelo nome das pastas.
Para criar nova documentação:
- Planeje a estrutura antes de começar a escrever
- Use templates existentes quando apropriado
- Teste os procedimentos antes de documentar
- Peça review de pelo menos um colega
- Mantenha atualizado conforme mudanças
Workflow de edição:
Dicas de edição:
- Use o editor Markdown para máxima flexibilidade
- Preview suas mudanças antes de salvar
- Adicione comentários explicando grandes mudanças
- Use o histórico para comparar versões
Revisão por Pares
Toda documentação crítica deve ser revisada por pelo menos um membro experiente do time.
Checklist de qualidade:
- Procedimento testado em ambiente real
- Comandos verificados e funcionais
- Pré-requisitos claramente definidos
- Troubleshooting documentado
- Formatação consistente
- Links funcionais
- Tags apropriadas
Altere seu nome e senha:
