Pular para o conteúdo principal

Boas práticas

Manter uma documentação clara, organizada e acessível é essencial para garantir que os usuários encontrem rapidamente as informações de que precisam. Este guia apresenta um conjunto de boas práticas para utilizar o Docusaurus de forma eficiente, garantindo padronização, qualidade e escalabilidade na documentação.

Por que seguir boas práticas?​

  • 📖 Facilita a leitura e compreensão – Estruturas bem definidas tornam a navegação intuitiva.
  • 🔄 Melhora a colaboração – Com padrões claros, qualquer pessoa pode contribuir sem gerar inconsistências.
  • 🚀 Aprimora a experiência do usuário – Um conteúdo bem organizado e otimizado torna o acesso à informação mais rápido.
  • 🔍 Garante SEO e indexação eficiente – Seguir padrões de metadados e acessibilidade melhora a visibilidade da documentação.

A seguir, você encontrará diretrizes essenciais para estruturar e manter sua documentação utilizando o Docusaurus da melhor forma possível.

1. Organização da estrutura​

  • Defina uma hierarquia clara: Utilize pastas e subpastas organizadas para facilitar a navegação.
  • Nomeie arquivos e diretórios de forma descritiva: Evite nomes genéricos como doc1.md. Prefira instalação.md, boas-praticas.md, etc.
  • Mantenha um índice custom-sidebar.js bem estruturado: Categorize documentos para facilitar o acesso. Acesse a página Menu lateral para saber como organizar o seu conteúdo.**

2. Padronização da Escrita​

  • Adote um guia de estilo: Defina padrões para tom de voz, estrutura dos títulos e formatação dos textos.
  • Evite textos longos e densos: Prefira parágrafos curtos, listas e exemplos práticos.
  • Use Markdown/MDX corretamente: Aproveite os recursos do MDX para incluir componentes interativos. Acesse a página Markdown para saber como criar o seu conteúdo em Markdown e MDX.

3. Controle de Versão​

  • Automatize revisões: Utilize pull requests para validar mudanças antes de publicar. Acesse a página Git flow para saber mais sobre o controle de versão.

4. Versionamento​

  • Habilite o versionamento de documentação: Se houver múltiplas versões do produto. Acesse a página Versionamento para saber mais sobre como criar versões do conteúdo.

5. SEO​

  • Configure metadados corretamente: Utilize title, description e keywords nos arquivos .md para melhorar SEO.

6. Experiência do Usuário​

  • Use uma navegação intuitiva: Menu lateral bem definido.
  • Inclua exemplos práticos e snippets de código: Facilita o entendimento técnico. Acesse a página Markdown para saber quais recursos estão disponíveis.

7. Monitoramento e Manutenção​

  • Mantenha a documentação sempre atualizada: Revise e arquive documentos obsoletos periodicamente.
  • Utilize o Google Analytics e o Clarity: Para entender como os usuários interagem com a documentação.