vale a pena ou mesmo necessário adicionar um ficheiro README em cada novo projecto. Hoje vamos nos concentrar em boas práticas de escrever tal arquivo-com alguns exemplos, e um modelo pronto para usar.
o que é um ficheiro README?
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. Um arquivo de texto README aparece em vários lugares e não se refere apenas à programação., Mas vamos concentrar-nos no README de um programador.
exemplo de README para uma gem Bootstrap (Ruby On Rails)
Added README file on GitHub appears under the list of files in a repository. se trabalharmos profissionalmente ou aprendermos codificação, muitas vezes deparamo-nos com repositórios públicos. Usamos as bibliotecas disponibilizadas por outros desenvolvedores como um código aberto ou fazemos nossa contribuição para um projeto, relatando/corrigindo bugs, e adicionando novas funcionalidades., Certamente, nós usamos esses projetos porque eles só vêm a calhar, e oferecem uma solução de alta qualidade. Mas usá-los-íamos se não tivessem uma descrição fácil de usar, ou seja, um bom README?
pode ter a certeza – você vai conhecer o sentimento de decepção ao encontrar uma solução potencial para todos os seus problemas em uma biblioteca ou um projeto que a descrição é pobre, inútil ou não está disponível de qualquer forma.
Qual é o uso de escrever um bom README?
eu acho que você já pode adivinhar., Um bom README é para outros entenderem o que nosso Código inclui, e por que é digno de nota. Um arquivo README também é essencial para retirar um projeto – no GitHub, mas também em navegadores (por exemplo, Google).
I am just learning so why should I be bothered about adding a README file? Esse código é apenas para mim, afinal, não para toda a comunidade.
duvido que o código seja apenas para você. E adicionar um arquivo README é uma boa jogada.,
README for Junior Devs
OK, now let’s check why we should care for our README files since the first project!
mesmo que o código seja apenas para você, possivelmente você vai voltar para ele depois de um tempo. Um bom README permite-lhe relançar um projecto – sem perder tempo a recordar: de que se tratava?
para um programador em ascensão, GitHub é um cartão de visita. Os projetos no GitHub são, na maioria das vezes, o nosso portfólio., Quando estamos em uma fase de carreira sem uma experiência comercial considerável ou projetos sem fins lucrativos bonitos, uma apresentação de nossas conquistas em uma forma de repositórios é uma das melhores maneiras de ficar visível para os recrutadores. A preparação de vários projetos de demonstração que queremos exibir durante a entrevista funciona melhor. se estamos apenas aprendendo e abandonamos nossos projetos de treinamento lá, vamos prestar atenção à sua boa descrição., Mesmo um recrutador não-técnico será capaz de reconhecer as tecnologias que tocamos, e verificar se ele vai de acordo com o perfil de um candidato que ele/ela está procurando.
em polaco ou em inglês?
certamente, em inglês. Adicione uma descrição do projecto em inglês, mesmo que o seu projecto esteja em língua polaca. Os projectos realizados na universidade podem ser tratados como uma excepção, uma vez que muitas vezes exigem uma documentação em polaco. Em todos os outros casos, descreva seus projetos em inglês.
README.md -espera, o que se passa?,
.md extension comes from a word: markdown. É uma linguagem de marcação para formatação de texto. Talvez no início não seja óbvio, mas a formatação foi criada para tornar a criação de texto mais fácil. Na linguagem HTML, o título mais importante vai com h1 tag. Similarmente, teremos # antes de um título em nosso documento.
we edit .md files in any text or code editor (Notepad, Sublime, Atom, CS, etc.).
Você vai descobrir mais sobre o uso do markdown no GitHub, e no dillinger.,você vai encontrar um editor com uma prévia.
Writing a good README-newbies manual
Open a README.md. file em um novo projeto.,
certifique-se de que o arquivo inclui sempre os seguintes elementos:
- Títulos internos e títulos
- Introdução – o objetivo do projeto
- Tecnologias
- Iniciar
Considere também o uso de elementos adicionais, tais como:
- índice
- Ilustrações
- Escopo de funcionalidades
- exemplo de uso
- status do Projeto
- Fontes
- Outras informações
isso é muito! Não há muito a dizer sobre o meu projecto!,
existe – mas você não está ciente disso já.
Títulos internos e títulos
Um título deve explicar claramente o que temos aqui, e é geralmente um nome do projeto – um cabeçalho H1 precedidos por #. Se o nome de um projeto não revelar seu conteúdo, ainda vale a pena sugerir o que é.
além disso, o texto deve incluir os títulos das secções, e – se necessário – os títulos internos. Para manter o nosso README coerente, escrevemo-los da mesma forma em todos os outros documentos. Em nosso README.,MD file, the headings should be written down with a multiple of #:
# header H1
## header H2
### header H3
#### header H4
##### header H5
###### header H6
Introduction
Introduction is like a summary. Não deve demorar muito, já que não queremos ler um ensaio sobre um projecto. Devemos descrever de forma interessante Qual é o objetivo do projeto,e quais os problemas que uma determinada aplicação resolve. Duas ou três frases são suficientes no caso de um pequeno projeto.se for um projecto de formação, mencione o seu incentivo. Por que você queria criá-lo? Para aprender uma tecnologia em particular? Foi um projecto hackathon?, Foi para uma organização sem fins lucrativos? É uma aplicação criada para memorizar o material das oficinas ou do curso online? Vale a pena mencionar aqui, sem dúvida.
Technologies
Let’s write down the languages we used, the libraries and its versions.
Por exemplo:
- Bootstrap 3 ou 4
- AngularJS 1.6 / Angular 2+/4/5/6
- PHP 5 ou 7
- Python 2.7 ou 3,6
- Rails 4 ou 5
Por quê? Em primeiro lugar, será útil no lançamento do projecto no futuro., As versões das bibliotecas mudam, e uma mudança discreta pode causar muitos problemas mais tarde. É bom saber a versão que foi usada quando nosso código estava funcionando exatamente como queríamos. outra coisa: recrutamento. Recrutadores navegam pelas contas dos candidatos. Apesar de não possuírem um conhecimento técnico para estimar a qualidade das soluções, conhecem as palavras-chave relacionadas com as suas ofertas de emprego. Uma descrição das tecnologias usadas pode fazer você se destacar entre outros candidatos., vamos assumir que há uma multidão de candidatos para um estágio, e o tempo de recrutamento é limitado. Os CVs foram selecionados, há dois candidatos similares e uma última data Disponível em um calendário. As contas do GitHub dos candidatos incluem o mesmo número de projetos. Uma delas menciona as tecnologias em todos os projetos. Um segundo candidato não adiciona arquivos README ou seus projetos são mal descritos. O que você acha, que CANDIDATO será convidado para uma entrevista?
Launch
How to run a project? Um projeto tem requisitos mínimos de hardware?,nós mencionamos as bibliotecas e suas versões mais cedo. Se necessário, os requisitos de tecnologias, lançamento e hardware podem ser unidos. Mas se a dividirmos em duas subsecções, vale a pena focar aqui especificamente no lançamento de um projecto. Quando temos um site ou aplicação, ele pode se preocupar com a criação de um ambiente local, um link para páginas GitHub ou aplicativo implantado em Heroku. Precisamos de dados de entrada? Em caso afirmativo, em que formato?vamos focar em outros elementos que podem melhorar o nosso README.,
tabela de conteúdo
tabela de conteúdo vem a calhar em caso de extensa documentação. Pode funcionar como uma lista simples com os links para os cabeçalhos.
And it will look like:
ilustrações
GitHub allows for graphics in README. Uma documentação técnica não precisa de ser bonita, mas legível e compreensível. As ilustrações não são necessárias – no entanto, podem ser estéticas para o nosso projeto. Você pode mostrar o logotipo de uma aplicação, diagramas, esquemas, imagem exemplar., Talvez queiras um manual ilustrado?
crie um arquivo em seu repositório, e adicione uma imagem lá. Use um caminho de arquivo para mostrá-lo usando: !(ścieżka/do/pliku). Você pode usar as imagens do além você repositório, se eles estão publicamente disponíveis, mas há sempre um risco de que o proprietário dessas fontes elimine-os a partir de seu domínio, e eles vão desaparecer da sua documentação: !(url grafiki)
Exemplo: No meu arquivo LEIAME, eu quero colocar um bloco de esquema que iria ilustrar como um algoritmo funciona., Eu guardo o meu esquema.ficheiro jpg numa pasta chamada images. Para mostrá-lo na minha documentação, usarei um código:
!(./images/schema.jpg)escopo das funcionalidades
não há sempre uso para descrever o escopo das funcionalidades. Para um cartão de visita de um site ou uma simples aplicação de tipo de item por – fazer, a lista de funcionalidades é um excesso de forma.,
por outro lado, um aparentemente simples do projecto, tais como lista de tarefas pode ser estendido com muitas opções interessantes de que nos podemos orgulhar: os usuários registrar, gravar e distribuir as tarefas de acordo com a data, adicionar comentários às tarefas ou exportação de dados para arquivos.
exemplos de Utilização
No caso de um código reutilizável ou da sua própria biblioteca, pode ser necessário fornecer um manual de Utilização do nosso projecto., Ele pode funcionar como um fragmento de código:
## Code ExamplesTo generate lorem ipsum use special shortcode: `put-your-code-here`o que vai ser apresentado como:
O status do projeto
vale a pena adicionar um projeto de estado – especialmente se o projeto ainda está sendo desenvolvido. Se é a nossa biblioteca, vamos mencionar mudanças planejadas, direção de desenvolvimento ou para enfatizar que terminamos com o seu desenvolvimento.
fontes
devemos adicionar informação quando o nosso projecto foi baseado num tutorial ou fomos inspirados numa dada tarefa? Sim, claro.
I don’t get the doubts in that matter., Não há nada embaraçoso no facto de aprendermos com várias fontes e documentarmos o nosso progresso. Completamos muitos tutoriais, Escolhemos material de aprendizagem. Uma cópia irreflectida sem fornecer mudanças nela – e sem aprender nada – na maioria das vezes não acontece. se o nosso código foi baseado no código de outra pessoa, devemos adicionar essa informação.
talvez nós usamos um tutorial antigo-por exemplo, nós escrevemos uma aplicação com tutorial Rails 3. A partir do zero, de acordo com a versão Carris 5, utilizando novos mecanismos de enquadramento. Certamente, vale a pena mencionar aqui.,
Quando o nosso código foi inspirado apenas por outra solução / uma aplicação, pode mencioná-lo e escrever a forma como se inspirou, quais as alterações que fez, quais as funcionalidades que foram desenvolvidas.
quando resolvemos os conjuntos de exercícios, vale a pena adicionar onde os outros podem encontrar a sua descrição. Se quisermos voltar a estas fontes, a ligação surgirá facilmente. Desta forma, o autor que compartilhou seu conhecimento é, gastou seu tempo para preparar e compartilhar este material também é respeitado.,
Outras informações
sobre o autor, entre em contato, www e links de mídia social, um tipo de licença sob a qual o código está disponível ou informações sobre como contribuir para um projeto – estes são apenas exemplos do que pode ser adicionado ao seu projeto.
a good, legible README
The suggestions above are mine. O ponto mais importante é apenas a legibilidade. Uma documentação completa faz o seu repositório brilhar na frente dos recrutadores e outros programadores. Há muitas abordagens para escrever um bom README., Dê uma olhada nos seguintes exemplos:
- Node-chat – uma descrição simples, imagem da aplicação, exemplos de uso
- WebApp – um exemplo esplêndido de descrição fornecida para um tipo de página de destino do site e aplicação usando API. Descrição de como ele funciona, imagens, tecnologias empregadas nesta solução, obter informações adicionais sobre funcionalidades que serão implementadas
- Pomolectron – temos uma logomarca, as telas, as instruções sobre a instalação e uma descrição de como funciona
- Git ponto – exemplar aplicativo para Android., Uma tabela de conteúdo torna a navegação mais fácil, as imagens, as funcionalidades mencionadas e a informação sobre como suportar o desenvolvimento da aplicação
readme template
deixo-o aqui um exemplo de README.md modelo de ficheiros que pode transferir. Dê uma olhada em sua formatação, e copie uma versão raw para o seu README.md file.
O artigo também está disponível em polaco em Flynerd.pl blog.