Dicas para um otimo arquivo leiame (e por que isso é importante)

Jan 19, 2020 · 6 min de leitura

Nós, desenvolvedores, são muito boas com o código e todos os detalhes dos nossos projetos. Mas alguns de nós (me incluído) falta em soft-skills mesmo na comunidade online.,

um desenvolvedor iria passar uma hora ajustando o enchimento e a margem de um único botão. Mas não poupava 15 minutos para o ficheiro Readme descrição do projecto.

readme.md file é e para que é usado. Mas para os novatos aqui vou tentar explicar o que é exactamente.

o que é a Readme.md?

README (como o nome sugere:” leia-me”) é o primeiro arquivo que se deve ler ao iniciar um novo projeto., É um conjunto de informações úteis sobre um projeto e uma espécie de manual. É o primeiro arquivo GitHub ou qualquer site de hospedagem git vai mostrar quando alguém abre o seu repositório..

Como você pode ver claramente aqui leia-me.md o arquivo está na raiz do repositório, e é apresentada automaticamente pelo github abaixo do diretório de projeto.

And The.mdextension comes from a word: markdown., É uma linguagem de marcação para formatação de texto. Assim como HTML é uma linguagem de marcação para tornar os nossos documentos apresentáveis.

Aqui está um exemplo de um arquivo markdown e como ele se torna no github na verdade. Eu uso o VSCode aqui para a antevisão que mostra uma antevisão dos arquivos de marcação simultaneamente.

Aqui está um oficial Github planilha para o formato Markdown se você precisa profundezas para habitar na língua.agora vamos falar de negócios., Passou horas num projecto, tornou-o público no GitHub e quer pessoas/recrutadores / colegas / (Ex?) veja o seu projeto. Você realmente acha que eles iriam para root/src/app/main.js para ver essa sua lógica bonita? A sério?agora que tenho a tua atenção, vamos ver como resolver isto.gerar documentação para os seus componentes

para além do readme do seu projecto, documentar os seus componentes é crucial para uma base de dados de código compreensível. Torna muito mais fácil reutilizar componentes e manter o seu código., Use ferramentas como o Bit (Github) para gerar automaticamente documentação para componentes partilhados no bit.dev

Exemplo: a busca por componentes compartilhados em Bits.dev

descreva o seu projecto! (TL; DR)

escreva uma boa descrição dos seus projectos. Apenas para orientações, você pode formatar a sua descrição nos seguintes tópicos: –

  • título (uma imagem de Título também, se possível…Edite-os no canva.,com se você não é um designer gráfico.)
  • Descrição(Descrever por palavras e imagens iguais)
  • Demo(Imagens, links para vídeos, Demonstração ao Vivo de links)
  • Tecnologias Usado
  • Dicas Especiais de seus projetos (Problemas que você enfrentou, únicos elementos de seu projeto)
  • Descrição Técnica do projecto como Instalação, Configuração, Como contribuir.

vamos mergulhar profundamente em tecnicalidades

vou usar este meu projeto como referência, que eu acho que tem um dos arquivos readme mais bonitos que eu escrevi e até mesmo veio através., Você pode conferir o código do arquivo Leiame.md arquivo aqui:

Use o ícone de lápis para mostrar o markdown código :-

ADICIONAR IMAGENS! Por favor!

pode ter uma memória fotográfica, mas os seus leitores podem precisar de algumas fotografias reais da demonstração do seu projecto.

Por exemplo, eu fiz um projeto solitário e adicionei imagens como uma descrição no readme.,

Now you may want to add a video description of your projects too. Just like I did. BUT… Github doesn’t let you add a video to the readme… So… So what?

…WE USE GIFS

HAHA… Got ya Github.,

Gifs caem na categoria de imagens e github permite que você as tenha em seu readme.

o crachá de honra

Os crachás no seu readme dão ao espectador alguma sensação de autenticidade., Você pode obter personalizado/usados regularmente escudos(crachás) para o seu repositório:- https://shields.io

Você pode obter personalizados escudos, tais como o número de estrelas no repositório de código e a percentagem de indicadores também.

adicione uma demonstração ao vivo

Se possível obtenha o seu projecto hospedado e configure uma demonstração em execução. Depois disso, LINK esta DEMO para o seu README., Não fazes ideia de quantas pessoas podem acabar a brincar com os teus projectos. E o recrutador adora projectos ao vivo. Mostra que os teus projectos não são apenas uma lixeira de código no github e tu realmente falas a sério.

Você pode usar Hiperlinks no leia-me. Então dê um link de demonstração ao vivo logo abaixo da imagem de título.

Use Code Formating

Markdown dá-lhe a opção de formatar o texto como código., Portanto, não escreva o código como texto sem formatação em vez de utilizar ” (Til) para encapsular o código dentro do código de formatação tais como var a = 1;

Github também lhe dá a opção para especificar o idioma em que o código é escrito em forma que ele pode usar o texto específico realce para tornar o código mais legível. Para fazer isso, use

“{língua-extensão}<espaço>{bloco de Código Dentro}“

{ “ }- Triplo til é usado para multi-linha de código e também permite que você especificar o idioma do bloco de código.,

With Language Highlighting:-

Without Langage Highlighting:-

Use of HTML

Yes, you can use HTML inside. Not all the features though. But most of it., Embora você deve ficar apenas ao markdown, mas, algumas características como centralizar imagens e texto no readme só é possível pelo HTML.