DEV Community

Tulio Calil for Devs Jequié

Posted on • Updated on • Originally published at tuliocalil.com.br

Criando Readme incríveis! 📖

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) ?

Hey, eu atualizei esta postagem no meu blog pessoal, veja agora!

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.
Aqui também é legal implementar versões de imagem para cada tema (light ou dark) caso seu repositório esteja no Github, você pode fazer isso vendo este post
Uma dica 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.




Top comments (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

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.