Deploy na Sexta #22: Ouviu falar de documentação de código?
Começando pelo básico, um bom README.
Quando tomei a decisão de me tornar programadora, dediquei-me intensamente aos estudos, o que envolvia desenvolver diversos projetos para enriquecer meu portfólio. Utilizava uma variedade grande de tecnologias, e bibliotecas dentro do universo CSharp para atender aos requisitos exigidos pelas vagas de emprego. Certa vez, durante um ensaio de entrevista com um amigo, ele escolheu aleatoriamente um dos projetos da minha pasta. Pediu para explicá-lo e: Travei, não lembrava nem do que se tratava aquele código.
A partir daquele dia, por não temos interfaces visuais que ilustrem o que foi desenvolvido em um backend, adotei as documentações no meu portfólio para nunca mais me perder. Um bom começo para documentação são os READMEs, pois fornecem uma introdução clara e acessível aos seus projetos. Eles são extremamente úteis não apenas para organizar teu portfólio, mas também uma habilidade técnica importante.
Além disso recrutadores frequentemente têm pouco tempo para avaliar um candidato inicialmente. Um README claro e conciso dá a eles uma rápida compreensão das suas habilidades técnicas e do teu estilo de trabalho. Ele permite que identifiquem rapidamente se suas experiências, linguagens e tecnologias dominadas estão alinhadas com as necessidades da vaga.
Afinal, o que colocar em um README? 🤔
Visão Geral do Projeto: Inicie com uma descrição geral e informativa do teu projeto. Explique claramente o que o projeto realiza e qual problema visa resolver. Esclareça o contexto ou a motivação por trás da criação do projeto, ajudando os leitores a entender a solução proposta.
Tecnologias Usadas: Liste todas as tecnologias, frameworks e ferramentas usadas no desenvolvimento do projeto, explicando brevemente por que escolheu essas ferramentas específicas e como elas contribuíram para os objetivos do projeto. Essa seção não só mostra tuas habilidades técnicas, mas também sua capacidade de escolher a tecnologia adequada para resolver problemas específicos.
Detalhes Técnicos e Guia de Instalação: Liste os requisitos necessários para instalar e executar o projeto. Inclua um link para um documento detalhado que orienta como realizar a instalação passo a passo. Caso usuários possam baixar tua aplicação para consumir.
Uso do Projeto: Forneça uma visão geral ou exemplos de como os usuários podem utilizar o projeto na prática e quais problemas a aplicação resolve.
Recursos Adicionais: Disponibilize links para documentação adicional de tecnologias utilizadas, artigos, blogs, demos e outros recursos externos que complementam o uso do projeto.
Exemplo de Estrutura
Nos READMEs, usamos Markdown, uma linguagem de marcação que tu podes usar para adicionar elementos de formatação a documentos de texto. Além disso, plataformas como GitHub, Bitbucket e GitLab interpretam automaticamente arquivos Markdown (geralmente com a extensão .md) e exibem o conteúdo formatado na interface do usuário, deixando a apresentação do teu projeto linda.
Montei um READMEs de exemplo para ti:
# Nome do Projeto
## Descrição
Descreva aqui o que o seu projeto faz e o problema que ele resolve. Inclua uma visão geral sucinta do que o sistema é capaz de fazer e para quem ele é destinado. Se possível, mencione os diferencias do projeto que o destacam.
## Índice
- [Instalação](#instalação)
- [Como Usar](#como-usar)
- [Contribuindo](#contribuindo)
- [Equipe](#equipe)
- [Feedback e Contato](#feedback-e-contato)
- [Licença](#licença)
## Tecnologias Usadas
Liste as tecnologias, frameworks e bibliotecas utilizadas no projeto. Exemplo:
- Node.js
- React
- MongoDB
## Instalação
### Pré-requisitos
Antes de começar, verifique se tu atendeu aos seguintes requisitos:
- Tu instalou a versão mais recente de `node.js`
- Tu tem uma máquina `Windows/Linux/Mac`.
### Configuração
Para instalar o Nome do Projeto, siga estes passos:
Linux e macOS:
\`\`\`bash
sudo apt-get install nome_do_projeto
\`\`\`
Windows:
\`\`\`bash
install nome_do_projeto
\`\`\`
## Como Usar
Após a instalação, tu pode usar o projeto da seguinte maneira:
\`\`\`bash
nome_do_projeto --option ARG
\`\`\`
Inclua exemplos de como usar o projeto. Isso pode ser em forma de código ou linhas de comando. Certifique-se de explicar o que cada comando faz.
## Contribuindo
Contribuições são o que fazem a comunidade open source um lugar incrível para aprender, inspirar e criar. Quaisquer contribuições que tu fizer são **muito apreciadas**.
Se tu tem sugestões para melhorar este projeto, siga estes passos:
1. Bifurque o projeto
2. Crie uma Branch (`git checkout -b feature/AmazingFeature`)
3. Faça suas alterações no código
4. Confirme suas alterações (`git commit -m 'Add some AmazingFeature'`)
5. Envie para a Branch (`git push origin feature/AmazingFeature`)
6. Abra um Pull Request
Não se esqueça de ler o `CONTRIBUTING.md` para detalhes sobre o código de conduta, e o processo para enviar pull requests para nós.
## Equipe
Liste os membros da equipe que contribuíram para este projeto. Exemplo:
- [@fulano](https://github.com/fulano) - Ideia & Desenvolvimento inicial
- [@beltrano](https://github.com/beltrano) - Documentação
- [@sicrano](https://github.com/sicrano) - Manutenção
## Feedback e Contato
Para enviar feedback ou entrar em contato, por favor, envie um e-mail para `seu_email@example.com`.
## Licença
Este projeto está licenciado sob a Licença XYZ - veja o arquivo [LICENSE.md](LICENSE.md) para detalhes.Tá, e aquela área contribuição? São qualquer forma de participação de outras pessoas que ajude a melhorar ou expandir o projeto. Isso inclui adicionar novas funcionalidades, corrigir bugs, otimizar o código existente, melhorar a compatibilidade do software com plataformas ou versões de dependências.
Já as licenças de software definem como o software pode ser usado, modificado e distribuído, em outras palavras, elas dizem o que outros podem ou não fazer com o teu código. As licenças mais usadas são: MIT, GPL, Apache 2.0, BSD, eu uso MIT que é a mais permissiva, mas posso criar uma edição da newsletter só sobre esse tópico te explicando cada uma delas.
Por fim, a documentação é uma habilidade técnica importante, mas pouco falada. Nas empresas ela é fundamental para o sucesso de qualquer projeto, porque situa quem entrará no projeto e proporciona uma colaboração eficaz entre desenvolvedores. Tenho certeza que se tu te concentrar em fornecer clareza e acessibilidade através de um README, tu causarás uma boa impressão sobre teu projeto e sobre o profissional que és.
Já trabalhou em projetos sem documentação e sem README? Nossa é uma experiência traumatizante precisar ler linha a linha de um código, debugar para só então entender qual é a proposta. Me conta nos comentários, as dicas de hoje te ajudaram? Faltou alguma dica sobre como construir bons READMEs?
🧠 Exercício da Semana
Além do modelo que eu trouxe nesta edição, existem vários geradores de README na internet para te ajudar a construir uma documentação bem legal. Separei algumas ferramentas que eu já testei:
Readme.so: Um site super intuitivo com editor de markdown e modelos de readme para usar nos teu projetos.
Make a Readme: Um guia para te ajudar a escrever um readme para teu projeto, com manual de uso nos principais repositórios e modelo editável para começar.
ChatGPT: Forneça informações sobre o teu projeto como: descrição, tecnologias usadas, como instalar, usar, contribuir e assim por diante. Com esses dados, ChatGPT pode ajudar a escrever um README detalhado e bem estruturado.
Lembre-se, o arquivo README serve como introdução ao teu projeto, ele representa apenas o primeiro passo em direção a uma documentação de software. Uma documentação pode incluir documentação de API, manuais do usuário, exemplos de código, FAQs, e até mesmo vídeos tutoriais, dependendo da complexidade e do escopo do projeto. Se tu curtiu esse conteúdo, me conta nos comentários, pois posso falar mais sobre documentação.
📅 Eventos no Radar
25 e 26/04 Brasil JS: estarei na maior conferência JavaScript do mundo, como apresentadora, nos encontramos lá em Porto Alegre?
06 a 10/05 Imersão IA Gratuita: A Alura e o Google se uniram para te ajudar a dominar as ferramentas de Inteligência Artificial em uma semana de evento online.
Obrigada por ler até aqui🖖
Nos encontramos no próximo deploy, sexta às 6:00.