Depois de desenvolver aquele projeto incrível, ter passado vários perrengues com a aplicação e Git, você abriu no Github para a comunidade.
Mas as suas tarefas não terminaram, está na hora de documentar o seu projeto! E nada melhor do que um bom README.md.
Tópicos deste artigo
- O que e o README
- Por que usá-lo
- Estrutura do README
- Titulo e descrição do projeto
- Como usar Badges
- Funcionalidades da Aplicação
- Emojis
- Status do projeto
- Deploy da aplicação? Oba
- Poxa, mas meu projeto ainda não está no ar, e agora?
- Imagens
- Rodando o seu projeto
- Dados, dados e mais dados
- Como rodar os testes?
- Acabou o projeto?
- Não esqueça dos amiguinhos
- Dependências e tecnologias
- Resolvendo problemas
- Fechando com chave de ouro
- Deixe a preguiça de lado
- Presente
O que é o README
Ele é basicamente um arquivo de texto que pode ser escrito a partir de tags HTML ou Markdown. Pessoalmente costumo misturar os dois pois usando HTML consigo centralizar os elementos. Neste artigo não vou focar muito em como utilizar essas tags e sim na estrutura da documentação em sí. Se quiserem saber como utilizá-las recomendo este artigo excelente do Raul Esteves.
Por que usá-lo
Ele é mais que uma forma de documentação, é o cartão de visita para o seu projeto e vai fazer com que as pessoas que visitem o seu perfil do Github passem mais tempo olhando o você produziu.
Neste artigo eu vou recriar o README.md que fiz para o projeto Certificates for Everyone, mas se você estiver com pressa, já deixo aqui um resumo deste artigo:
Estrutura do README
- Titulo
- Status
- Tabela de Conteúdos
- Descrição
- Layout ou Deploy da aplicação
- Pré-requisitos
- Dependências e Libs Instaladas
- Como rodar a aplicação
- Como rodar os testes
- Database
- Solução de problemas
- Contribuintes
- Tarefas em aberto
- Licença
A primeira coisa a se pensar é na estrutura dessa documentação, podemos ter algo parecido com:
Titulo e descrição do projeto:
Coloque o nome do seu projeto. Exemplo:
# Titulo
ou
<h1 align="center"> Titulo </h1>
Seguido de uma descrição breve sobre ele:
## Descrição do Projeto
<p align="justify"> Escrever descrição, que ficará com texto justificado </p>
A tag align é usada para alinhar os elementos e assume left por padrão.
Perceba que aqui eu também inseri uma arte para o meu projeto, que poderia inclusive substituir o titulo. É algo que deixa o README.md mais bonito mas é completamente opcional
Como usar Badges
Badges servem para certificar ou indicar algo do teu projeto como status, licença, linguagens, testes, etc. Para saber mais acessem a documentação.
Para utilizados podemos entrar o site shields.oi. Lá é possível encontrar vários modelos prontos, mas hoje eu vou mostrar com personalizar um.
Podemos fazer isso a partir de uma URL como esta:
https://img.shields.io/static/v1?label=<LABEL>&message=<MESSAGE>&color=<COLOR>&style=<STYLE>&logo=<LOGO>
Onde cada parâmetro significa:
- LABEL texto do campo esquerdo
- MESSAGE texto do campo direto
- COLOR cor do campo direito (as opções podem ser encontradas no site)
- STYLE estilo do badge inteiro. Podemos ter: plastic, flat, for-the-badge, social ou flat-square.
- LOGO logo do campo esquerdo
Como exemplo, vou escolher os seguintes parâmetros:
- LABEL como react
- MESSAGE como framework
- COLOR como blue
- STYLE como for-the-badge
- LOGO como REACT
Podemos colocar ele no README assim:
<img src="https://img.shields.io/static/v1?label=react&message=framework&color=blue&style=for-the-badge&logo=REACT"/>
ou ainda:
E tcharam!! Temos um badge personalizado
Outra mágica do shields é que podemos copiar a URL do projeto no github e colar no campo de busca do site. Em seguida, ele te dará badges personalizados de acordo com o teu repositório:
Escreva as principais coisas que a sua plataforma pode fazer
Seria bacana listar as principais funcionalidades que sua aplicação oferece a partir de listas, poderíamos fazer de algumas formas:
### Listas não ordenadas
- Cadastro de conta com Google
- Captura de avatar a partir do login ou registro com google
### Usando um task list, marcando tarefa como completada ou não
- [X] Cadastro de conta com Google
- [ ] Cadastro de conta com Google
### Lista ordenada
1. Listagem ordenada
Emojis
Para deixar os títulos e listas mais divertidos costumo acompanhá-los com algum emoji que representam aquele tópico. É possível encontrar vários neste repositório. Para usá-los, basta copiar o nome da tag e usar no README.md Exemplo:
## O que a plataforma é capaz de fazer :checkered_flag:
:trophy: Gerar PDF do certificado com as informações preenchidas no formulário para cada participantes para envio de e-mail
:trophy: Check-list de participantes, permitindo selecionar quem irá receber os certificados
:trophy: Permite que o organizador do evento escreva sua assinatura digital dentro da plataforma
E teremos como resultado:
Status do projeto
Indique se seu projeto ainda está em desenvolvimento ou concluído, isso ajuda muito quem acompanha o seus trabalhos.
> Status do Projeto: Concluido :heavy_check_mark:
> Status do Projeto: Em desenvolvimento :warning:
Deploy da aplicação? Oba
Se for possível subir a aplicação com Netlify ou outras plataformas que permitem com que as pessoas acessem o seu projeto sem ter o trabalho de rodar em suas maquinas é ótimo, isso poupa tempo e paciência. Se tiver, coloque na documentação:
## Deploy da Aplicação com Netlify: :dash:
/* Aqui estamos usando a tag Quotes do markdown*/
> https://certificates-for-everyone-womakerscode.netlify.app/
Poxa, mas meu projeto ainda não está no ar, e agora?
Já dizia aquele ditado: "Quem não tem cão caça com gato". Aqui é a mesma coisa, coloque prints do layout do projeto (no caso de uma aplicação frontend), assim o visitante já poderá ter uma imagem do que você fez.
Beleza, mas como eu coloco imagens?
Existe o jeito não tão legal de fazer, mas funciona:
- Abra uma issue
- Insira uma imagem
- Um link como este será gerado:
 - Copie e cole no README.md e tcharam! A imagem irá aparecer!
A forma mais segura de fazer:
- Suba no seu repositório a imagem desejada. Ela ficará junto com os outros arquivos de código.
- Acesse a imagem e copie a URL, que pode ser algo parecido com:
https://github.com/Diana-ops/womakerscodeReact/blob/master/api-cep/src/assets/background.png - Use uma tag
imge insira o link emsrc
Também é possível capturar imagens da própria web, usando a URL assim como nesses passos que eu mostrei, mas isso não é muito seguro, pois a imagem pode ser deletada posteriormente.
E se alguém quiser rodar o projeto na maquina?
Esse é um tópicos mais importantes da documentação, principalmente quando falamos de código open source. O primeiro passo é escrever os pré-requesitos que ele precisa para rodar, como o yarn, npm, gem, bundle, etc.
Depois deixe um passo a passo bem bacana para outros devs, indicando todos os comandos de instalação e execução e em que pasta executa-los.
Dependências e tecnologias
Sobre colocar as linguagens eu já antecipo: depende. O próprio Github já indica as linguagens dos arquivos lá no topo do diretório.
Então se já estiver tudo lá, não há necessidade de colocar de novo. Mas caso tenha usado alguma lib extra como React Routes, React PDF, Antdesign é bacana colocar.
Eu não vejo necessidade em se aprofundar em como instalar cada uma dessas dependências, pois um yarn install ou bundle já irão fazer isso e as instruções para instalar cada uma das libs podem ser encontradas na própria documentação.
O que pode ser feito aqui é utilizar os links dessa forma:
## Linguagens e libs utilizadas :books:
- [React PDF](https://react-pdf.org/): versão xx.xxx
Assim o visitante verá uma lista de todas as dependências e o link já redireciona para a documentação. Se for o caso, indique a versão necessária para rodar o projeto.
Dados, dados e mais dados
Caso a sua aplicação conte com um backend ou JSON você pode deixar uma amostra na documentação. Podemos usar tabelas, que são uteis para organizar diversas outras informações. As colunas são divididas pelas barras e o título principal do conteúdo são separados pelos traços.
### Participante:
|name|email|present|receiveCertificate|course|
| -------- | -------- | -------- |-------- | -------- |
|Chaiana Hermes|chaiana_hermes@yahoo.com.br|true|false|Bootcamp React|
Como rodar os testes?
Os testes são boas práticas utilizadas em projetos (caso nunca tenha feito, comece já) e independente da linguagem que estiver usando sempre vai ter um comando para executa-los e é importante documentar. Exemplo:
/*Para projetos com React*/
$ npm test
/*Para projetos com Rails*/
$ rspec
Acabou o projeto?
Pode ser que ainda faltem algumas funcionalidades para serem implementadas ou refatorações em alguma parte do código. Aqui é o momento de listar quais tarefas estão abertas em issues ou no próprio README.md caso esteja aberto para receber contribuições e ajuda.
Não esqueça dos amiguinhos
Quando fizer aquele projeto em grupo ou receber alguma Pull Request como contribuição destaque-os. Uma coisa bem bacana aqui é misturar imagens com tabelas:
[<img src="https://avatars2.githubusercontent.com/u/46378210?s=400&u=071f7791bb03f8e102d835bdb9c2f0d3d24e8a34&v=" width=115 > <br> <sub> Diana Regina </sub>](https://github.com/Diana-ops) |
| :---: |
Confuso? Calma que eu explico.
Dentro de || temos uma tag html
<img>, nela foi definido o link e o tamanho da imagem com src e width. Aqui foi inserido o avatar do dev.Depois temos a tag
<br>, que faz uma quebra de linha com o próximo elemento colocando-o em baixo da imagem.Dentro de
<sub>colocamos o nome dele.Em seguida, juntamos a imagem e o nome dentro de [] seguido do link do github em ()
Por fim, os elementos são organizados em uma 'micro tabela', obtendo como resultado algo parecido com:
Para inserir mais devs, basta adicionais mais colunas.
Resolveu perrengues durante a aplicação? Documente!
É inevitável que erros ocorram durante a execução do projeto, a gente se estressa, passa horas no stackoverflow e em issues procurando respostas. Apesar de conseguir resolver, pode ser que alguma hora eles voltem e não existe nada pior do que esquecer de como resolver.
Não passe mais por isso! Quando tiver algum problema abra uma issue, apresente os erros e mostre como resolver, isso vai salvar a sua vida e a de outros devs em outros projetos. É uma forma sensacional de contribuir pra comunidade.
Claro, você pode deixar isso explicado no README.md também:
### Resolvendo problemas
Veja alguns problemas que surgiram no desenvolvimento deste projeto e como os resolvi em [issues](https://github.com/Diana-ops/treina-dev-turma-3/issues)
Ei, posso copiar o seu projeto?
A sua aplicação pode ter algum tipo de licença, que da direitos e restrições ao que as pessoas podem fazer com ele é muito importante que você deixe isso claro.
A licença mais utilizada é a MIT, que permite que qualquer pessoa possa usar, modificar e distribuir o seu projeto, mas te resguarda sob qualquer responsabilidade.
Para inserir, acesse
- Insights > Community
- Clique em
addpara licence - Uma PR será aberta e ao aceita-la uma nova branch será criada
- Agora, o simbolo de MIT estará no seu diretório
Fechando com chave de ouro
Ufa, depois de ter mais esse trabalhão escrevendo a documentação podemos fazer uma lista de conteúdos (como se fosse um sumário) lá no começo do README.md que irá ajudar o visitante a ir direto ao tópico que ele quer.
### Tabela de Conteúdos
* [Nome do tópico visivel](#nome-do-tópico)
### Nome do Tópico
⚠️ Para referenciar o tópico substitua letras maiúsculas por minusculas
⚠️ Caso o tópico tenha traços, ponto de interrogação e exclamação escreva como se não tivesse, pois o markdown não consegue encontrar.
⚠️ Caso o tópico esteja acompanhado de um emoji, escreva-o ignorando o simbolo ::
Deixe a preguiça de lado
Não espere o projeto terminar para começar a documentação. Pelo contrário! Deixe isso como a primeira tarefa, assim você pode planejar e documentar ao mesmo tempo.
Lembrando, não é obrigatório colocar todas essas informações e muito menos nessa ordem, tudo vai depender do seu projeto e os tópicos apesentados aqui são apenas sugestões.
Presente
Obrigada por ler até aqui, montei um template no gits com a estrutura de README mostrada neste artigo. Espero que gostem ❤️
Top comments (27)
Menina, parabéns! Material completíssimo, didático e muito útil. Grato pela contribuição. Veja o meu resultado, conforme suas dicas: github.com/paulinhovba/DGP-Manager...
Muito bacana Paulo!! Gostei do desenvolvimento do README e achei o projeto interessante tambem!! Aproveito para elogiar o teu site pessoal, esta incrivel, muito bom!!
Minha cara, desculpe o "flood" de replyes! Ao postar, recebi mensagem de erro e tentei algumas vezes e todas acabaram entrando. Já deletei os outros posts.
Iniciativas como a sua enriquecem muito a experiência humana. Compartilhar é crescer.
Agradeço pelo elogio, foi feito com muito amor!
Caso queira contribuir, o projeto será disponibilizado no git ainda hoje. Sinta-se livre para utilizar como lhe convier.
Se precisar de algo, estou sempre às ordens.
Um abraço!
hahaha deve ser bug no site, aconteceu a mesma coisa comigo quando fui te responder. Aliás, me inspirei no teu portfólio para construir o meu: dianaregina.netlify.app/
Diana, bom dia! Adorei seu novo site. Ficou muito bom mesmo. Parabéns!
Obrigada :)
Muito Bom! TKS
Bacana demais o tuto Diana
Algum tempo atrás eu ainda esta nos tetos básicos no Github, agora quero deixá-los cada vez mais bonitos, para brilhar os olhos dos visitantes
muito obrigado em me ajudar
Obrigada JR, demais!! Só arrasa nos projetos agora :)
Excelente artigo. Tem está ferramenta que ajuda a criar uma estrutura inicial bem interessante de readme
Ótimo artigo! Parabéns!
Óptima explicação!
Devias fazer em inglês também 😉
Obrigada, é uma boa ideia :)
Vidas foram salvas!! Muito obrigada por compartilhar ^^'
Olá,gostaria de saber como que faz pra deixar em ''micro tabela'' nos desenvolvedores,fiz desse jeito,porém ficou um em baixo do outro
Olá Rafael, a base é fazer uma tabela:
Código:
Resultado:
Dentro de cada dev/coluna inserimos uma imagem
<img/>, quebra de elementos<br/>e texto<sub><sub/>dentro de um link[](). Dentro dos colchetes colocamos os elementos visiveis e nos parentes o link para o githubCódigo:
Resultado:
Nome do Dev
Outro nome do Dev
Exemplo para 2 colunas:
Código:
Resultado:
Diana Regina
Diana Regina
Exemplo para 4 colunas:
Código:
Resultado:
Diana Regina
Diana Regina
Diana Regina
Diana Regina
Umas das coisas mais lindas que já li
Obrigada :)
Ótimo artigo! Parabéns!
O melhor post que já encontrei sobre o assunto. Parabéns Diana!
Obrigado por compartilhar 📝 🚀
Muito obrigada, fico muito feliz :)
Muito massa. Usei bastante essas dicas no meu projetinho
Adorei seu artigo, parabéns e já estou usando pra editar o meu aqui. Muito bom menina, parabéns mesmo!
Muito obrigada :)
Muito legal esse post me ajudou muito vlw Diana ta de parabéns!
Ótimo post! Obrigada por contribuir! :-)