Manutenção de Conteúdo

Visão Geral

Este documento descreve as práticas recomendadas para manter e atualizar o conteúdo deste repositório de conhecimento. Seguir essas diretrizes garante consistência e facilita o processamento por agentes de IA.

Estrutura de Arquivos

Convenção de Nomenclatura

• Prefixo numérico: Use números para ordenar arquivos (ex: 1., 2., 3.)
• Nomes descritivos: Use nomes claros e descritivos em português
• Hífens para espaços: Use hífens ao invés de espaços (ex: manutencao-conteudo.md)

Exemplo:

1.primeiros-passos/
  1.para-agentes-ia.md
  2.introducao.md
  3.instalacao.md

Organização em Diretórios

• Diretórios numerados: Mantenha ordem lógica com prefixos numéricos
• Agrupamento temático: Agrupe documentos relacionados no mesmo diretório
• Profundidade limitada: Evite mais de 2-3 níveis de aninhamento

Frontmatter YAML

Campos Obrigatórios

Cada arquivo deve conter pelo menos:

---
title: Título da Página
description: Descrição breve do conteúdo
---

Campos Opcionais Recomendados

---
title: Título da Página
description: Descrição breve do conteúdo
navigation:
  icon: i-lucide-icon-name
  order: 1
seo:
  title: Título para SEO (pode diferir do title)
  description: Descrição para SEO
---

Ícones de Navegação

Use ícones do Lucide seguindo o padrão i-lucide-nome-do-icone:

• i-lucide-house - Página inicial
• i-lucide-file-text - Documentação
• i-lucide-code - Código
• i-lucide-book - Guias
• i-lucide-settings - Configuração

Formatação de Conteúdo

Títulos

• Use # apenas uma vez por arquivo (título principal)
• Use ## para seções principais
• Use ### para subseções
• Mantenha hierarquia consistente

Listas

Listas não ordenadas para itens sem ordem específica:

- Item 1
- Item 2
- Item 3

Listas ordenadas para sequências ou passos:

1. Primeiro passo
2. Segundo passo
3. Terceiro passo

Blocos de Código

Sempre especifique a linguagem:

```typescript
const exemplo = "código aqui";
```

Para arquivos com nome:

```typescript [arquivo.ts]
const exemplo = "código aqui";
```

Links

Links internos (para outros documentos):

[Texto do link](/caminho/para/arquivo)

Links externos:

[Texto do link](https://exemplo.com)

Idioma e Linguagem

Português do Brasil

• Todo o conteúdo deve estar em português do Brasil
• Use termos técnicos em português quando possível
• Mantenha consistência na terminologia
• Evite anglicismos desnecessários

Termos Técnicos

Quando necessário usar termos em inglês:

• Mantenha o termo original se for amplamente conhecido
• Adicione explicação em português na primeira menção
• Use itálico para termos técnicos em inglês: framework

Boas Práticas

1. Clareza e Objetividade

• Escreva de forma clara e direta
• Evite jargões desnecessários
• Use exemplos práticos quando apropriado
• Mantenha parágrafos concisos

2. Estrutura Consistente

• Comece com uma introdução breve
• Use seções para organizar conteúdo
• Inclua exemplos quando relevante
• Termine com resumo ou próximos passos quando apropriado

3. Metadados Completos

• Sempre inclua title e description
• Use description para resumir o conteúdo
• Adicione ícones de navegação para melhor UX
• Configure SEO quando relevante

4. Links e Referências

• Use links internos para documentos relacionados
• Referencie seções específicas quando apropriado
• Mantenha links atualizados
• Verifique que links externos estão funcionando

5. Exemplos de Código

• Sempre especifique a linguagem do código
• Use nomes de arquivos quando relevante
• Mantenha código atualizado e funcional
• Adicione comentários explicativos quando necessário

Checklist de Revisão

Antes de adicionar ou modificar conteúdo:

• Frontmatter completo com title e description
• Conteúdo em português do Brasil
• Hierarquia de títulos consistente
• Links internos funcionando
• Blocos de código com linguagem especificada
• Nomenclatura de arquivo seguindo convenções
• Ícone de navegação apropriado (se aplicável)
• Revisão ortográfica e gramatical

Versionamento

Commits

Use mensagens de commit descritivas:

feat: adiciona documentação sobre manutenção de conteúdo
fix: corrige links quebrados na seção de exemplos
docs: atualiza descrição do frontmatter

Pull Requests

Ao criar PRs:

• Descreva as mudanças realizadas
• Explique o motivo das alterações
• Verifique que não quebrou links existentes
• Confirme que segue as convenções estabelecidas

Ferramentas Úteis

Validação

• Linter Markdown: Use ferramentas para validar sintaxe
• Verificação de links: Valide links internos e externos
• Validação YAML: Verifique sintaxe do frontmatter

Edição

• Editor com preview: Use editores que mostram preview do Markdown
• Extensões: Use extensões para facilitar edição (ex: formatação automática)
• Validação em tempo real: Configure validação durante edição

Atualização de Documentos Existentes

Ao atualizar documentos existentes:

1. Mantenha estrutura: Preserve a estrutura geral quando possível
2. Atualize metadados: Revise e atualize frontmatter se necessário
3. Verifique links: Confirme que links ainda estão corretos
4. Mantenha consistência: Siga padrões estabelecidos no repositório
5. Documente mudanças: Use commits descritivos

Adição de Novos Documentos

Ao adicionar novos documentos:

1. Escolha localização: Determine diretório apropriado
2. Siga nomenclatura: Use prefixo numérico e nome descritivo
3. Crie frontmatter: Inclua todos os metadados necessários
4. Estruture conteúdo: Use hierarquia de títulos apropriada
5. Adicione links: Crie links de/para documentos relacionados
6. Revise: Siga checklist de revisão

Conclusão

Manter consistência e qualidade no conteúdo é essencial para que agentes de IA possam processar e utilizar efetivamente esta base de conhecimento. Seguir essas diretrizes garante que o repositório continue sendo uma fonte confiável e útil de informação.