Como ter um projeto bem documentado?

Olá leitores,

Hoje vamos falar um pouco sobre a criação desse site e como foi feito usando

Ele simplifica o processo de construção de sites estáticos para documentação técnica, tornando mais fácil para os desenvolvedores e equipes de projetos gerenciarem e apresentarem documentação online.

Algumas características-chave do Docusaurus incluem:

Estrutura de Documentação Padrão

Docusaurus fornece uma estrutura predefinida para organizar a documentação, incluindo suporte para múltiplos idiomas, categorias e versionamento.

Escrita em Markdown e integração com React

A documentação é escrita em Markdown, uma linguagem de marcação leve e fácil de aprender. Isso facilita a formatação e a escrita, permitindo que os desenvolvedores se concentrem no conteúdo, mas permite a incorporação de componentes React, proporcionando flexibilidade e interatividade quando necessário.

Pesquisa Integrada

Docusaurus inclui funcionalidades de pesquisa integradas para ajudar os usuários a encontrar rapidamente as informações desejadas.

Tema Personalizável

Embora Docusaurus venha com um tema padrão limpo e responsivo, os usuários podem personalizar a aparência do site de documentação conforme necessário.

Integração com Versionamento

É possível organizar documentação para diferentes versões de um projeto, facilitando a referência à documentação correspondente a uma versão específica do software.

Para iniciar o projeto instale o nodejs na ultima versão.

sudo apt-get install nvm -y
nvm install node

node --version  
v21.5.0

npx create-docusaurus@latest my-site classic

cd my-site

# buildando o projeto
npm run build #  irá gerar o código estatico
npm run serve

No navegador localhost:3000

A pasta my-site possui essa estrutura

.
├── babel.config.js
├── blog
├── build
├── docs # As documentações de exemplo estão aqui
├── docusaurus.config.js
├── node_modules
├── package.json
├── package-lock.json
├── README.md
├── sidebars.js
├── src
└── static

Claro que você pode fazer todos esses comando no próprio repositório do seu projeto e ele criará a pasta my-site com a estrutura acima.

Use o modelo na pasta docs e cria a documentação do projeto.

Toda vez que você quiser ver a documentação execute npm run serve

Você também pode montar uma pipeline de entrega para rodar o site em algum lugar e ter sempre a documentação mais atualizada para sua equipe e seus clientes!