DEV Community

loading...

Criando Readme incríveis! 📖

Tulio Calil
A software developer from Bahia, Brasil. 🚴🏼I love cycling | 🎮 PC Gamer | 👾 8/16 bits lover. Thank you for the 19k+ views 😍
Updated on ・4 min read

Preview
Você sabe criar arquivos readme para seus repositórios de uma forma atrativa e informativa, ou apenas deixa o readme padrão do React (just a joke) ?
Nesse post vamos ver alguns exemplos e dicas de como deixar nosso arquivo de readme super legal e organizado, então vamos por a mão na massa.md.

generated with Summaryze Forem 🌱

Badges

Github Badges
Badges são super legais para adicionar no nosso arquivo, além de dar um overview super rápido e deixar o projeto bem bonito.
Algumas que eu gosto muito de utilizar são as de tecnologia, dizendo algum framework/lib que utilizei, status da pipeline, stars e licença.
Alguns exemplos legais:
Type-graphql
Next JS
Firebase
Você pode criar suas próprias badges utilizando o shields.io ou pode encontrar varias prontas, inclusive nesse repositório aqui: https://github.com/Ileriayo/markdown-badges.

Logo

Criar uma logo ou utilizar algo pra representar é algo super legal e que da um toque super bonito pra o repo, é uma dica bem opcional, mas que faz muita diferença.
Uma dica que eu dou pra quem não tem tanta afinidade com design é utilizar serviços de criação de logo online, como o Launchaco ou encontrar uma logo open source aqui: https://openlogos.org/.

GitHub logo tuliocll / elixir-http-request

a study project with elixir to make N requests on some url

HttpRequest

A simple "application" to make requests n times for a url this is a study project with elixir and i used it to do a simple stress test on my server/database

Usage

You can execute the Iex and call the module and the function

iex -S mix
Enter fullscreen mode Exit fullscreen mode
iex(1)>HttpRequest.execute(5, 'https://www.google.com')
Enter fullscreen mode Exit fullscreen mode

This will make five request for 'www.google.com'. You can pass a token too:

iex(1)>HttpRequest.execute(5, 'https://www.google.com', 'Bearer 123123123')
Enter fullscreen mode Exit fullscreen mode

And you can check the doc running:

iex(1)> h(HttpRequest.execute)
Enter fullscreen mode Exit fullscreen mode

Made with in Bahia, Brasil.




Titulo e descrição

Titulo e descrição
Esse é super importante, lembre sempre de adicionar o titulo e a descrição do seu projeto de forma simples e bem direta.
Você pode criar o titulo e logo abaixo a descrição, ou criar uma sessão para a descrição depois do titulo.

Utilize as tags do markdown para isso:

# Meu projeto
Descrição do meu projeto...
Enter fullscreen mode Exit fullscreen mode

Gif ou imagem demo

É super legal quando a gente entra em um repo e tem logo de cara uma prévia do que esperamos ver, adicionar uma imagem ou um vídeo para isso é uma dica super valida.

GitHub logo tuliocll / summaryze-forem

Create posts summary from forem platform(like dev.to) easy

Summaryze Forem 📑

NodeJS JavaScript Next JS Vercel Dev.to blog Figma

About it📖

Inspired on my friend project: Summaryze, Summaryze Forem is a tool write on javascript with NextJS that use web scrap to get all anchor links from a post on forem plataforms(like dev.to), format it and create a markdown summary fast and easy I have this necessity after write this post and being too lazy to do the summary, so i decide to create this tool, hope you like it.

Here you can see the figma prototype.

Frameworks and Libs 🛠

  • Nextjs
  • Node Fetch
  • Cheerio
  • React Tabs
  • React Toastify
  • React Icons
  • ...

How to use it

Check here a quick guide.

Install 🚀

Clone the project:

git clone https://github.com/tuliocll/summaryze-forem.git
Enter fullscreen mode Exit fullscreen mode

Navigate to project folder and install dependencies:

cd summaryze-forem
yarn
#or
npm install
Enter fullscreen mode Exit fullscreen mode

Run the project on dev mode:

yarn dev
#or
npm run dev
Enter fullscreen mode Exit fullscreen mode

Buy me a coffe!

Ko-Fi

Made with

Sessões

Eu gosto de dividir o projeto em varias sessões: sobre, como funciona, como instalar etc...

Sobre

Gosto de criar uma sessão de sobre e detalhar mais sobre o projeto, o que me motivou, como ele foi feito etc.

Como utilizar

É legal uma parte falando como utilizar o projeto (caso seja necessário).

Instalar

Uma sessão mostrando comando a comando como instalar o projeto também é super valido.

Como rodar e como utilizar

Sempre deixo os comandos de como rodar em cada ambiente(caso seja o caso), prontos para serem copiados e colados.
Sessões

Demo

Demo de projeto
Caso seja possível, é sempre legal deixar um link de uma demo online, dessa forma, se for um projeto pessoal ou algum estudo que você fez, quem estiver vendo conseguirá ter a experiência de uso sem precisar fazer todo o processo de instalação.

Campos do Github

Preencha campos específicos do github, como: about e as tag.
Ajuda seu repositório ser encontrado facilmente e deixa mais organizado também.
Github

Utilize todo o poder do Markdown

Tabelas
O Markdown nos oferece coisas incríveis, assim como no html conseguimos criar links, tabelas, títulos e varias outras coisas. Eu recomendo duas coisas aqui nesse ponto, a primeira é que você leia essa documentação sobre as tags do markdown e a segunda é um editor em markdown online com varias dessas tags em forma de um editor de texto.

Bonus

Uma ferramenta online super legal e que conheci recentemente (depois de escrever esse post) foi o Readme.so. Você consegue criar readmes de forma mais visual e com uma padronização excelente!

Conclusão

Vou deixar aqui alguns repositórios meus que tem uns readme que eu gosto bastante e caso vocês queiram se inspirar.
Conhece algum repo que tem um readme muito legal ? Comenta pra gente!

GitHub logo tuliocll / rn-darkmode

Arquivos do tutorial Darkmode para React Native⚛️, confira no YT

Tutorial Darkmode com React Native⚛️ e Styled components💅🏾!

FollowersFollowersStarsFollow

📖Sobre

Este repositorio contem o projeto final e o projeto base para o tutorial do darkmode com styled components, Animação com React Native, Contexto e estado global com React Native e afins, confira na tabela mais abaixo.

🔀Branchs:

Nome da Branch Descrição
Master Conteúdo inicial do tutorial, projeto base.
darkModeComplete Tutorial do darkmode completo, todos os arquivos configurados e funcionando.
darkModeAnimation Conteúdo tutorial de animação e handle completo, configurado e funcionando.
darkModePersist Contéudo final do tutorial de persistência de dados e estado global, configurado e funcionando.

👨🏿‍💻Iniciando

Clonar o repositorio:

git clone https://github.com/tuliocll/rn-darkmode.git

Instale as dependencias:

yarn
ou
npm install

🎦Siga o(s) vídeo(s);

Tutorial Link
DarkMode StyledComponents https://youtu.be/nJN7UNZetlg
Animação Tutorial Pt.1 https://youtu.be/AAYd5Vob0jY
Animação Tutorial Pt.2 https://youtu.be/Qc3j55C_1U8
Context API e React Navigation https://youtu.be/cLkX5MtZjEo
Context API e Async Storage https://youtu.be/gPpH-mTEwbM
React Navigation: Alterando Rotas e Parâmetros https://youtu.be/C2k6kwSi9FY

🙅🏿‍♂️End




GitHub logo tuliocll / sagres-bot

Um bot que diz diariamente se o sagres está online ou não e posta no twitter.

Sagres Bot - Twitter

Sagres bot preview

Followers Stars Follow Node

Instalando Clonar o repositorio:

git clone https://github.com/tuliocll/sagres-bot.git

Dentro da pasta do projeto, instale as dependencias:

yarn
ou
npm install

Configure as api keys (você precisa criar uma conta de desenvolvedor no twitter) E por fim, é só rodar

node src/index.js

End




GitHub logo tuliocll / todo-google-chrome

Código utilizado para escrever o tutorial "Criando uma extensão para o Google Chrome com React", leia aqui:

Criando uma extensão para o Google Chrome com React

Este projeto foi utilizado como base para o tutorial que escrevi aqui no dev.to, clique para ler.


🚀 Rodando o projeto

Para rodar o projeto em modo de desenvolvimento, basta executar:

yarn start
#ou
npm start
Enter fullscreen mode Exit fullscreen mode

🔥 Gerando build

Para gerar build e usar a extensão, consulte o post aqui.

🎯 Me siga

Youtube Dev.to Twitter LinkedIn

Feito com 💙 na Bahia, Brasil.




Discussion (2)

Collapse
lucasscharf profile image
Aleatório

Gostei bastante sobre as dicas. Nunca havia considerado a questão de colocar uma demo ou gifs. Senti falta de falar um pouco sobre configurações/variáveis de ambiente no README. Sinto que isso é algo bem imopratante e que o README é umbom lugar para colocar essas informações.

Fiz um artigo com essa temática no ano passado (dev.to/lucasscharf/como-escrever-u...).

Collapse
tuliocalil profile image
Tulio Calil Author

Valeu!
Sobre o env é uma boa ideia também!
Normalmente eu não menciono as variáveis de ambiente no readme, eu curto documentar elas no .env.example, mas claro, isso é bem pessoal.