Whata fuck is README ?


Intro

Quando o assunto é tecnologia web temos que nos adequar a várias metodologias que hoje em dia estão em constante evolução. Assim acabamos inconsequentemente dando foco a conteúdos mais robusto e não damos uma certa ênfase a conteúdos simples.. que porém são extrema importância.
O arquivo README se encaixa nesse quesito e daqui em diante iremos falar sobre seus principais aspectos durante esse post..

Utilização,metodologias de escrita e significado.

O README é bastante utilizado quando o assunto é escrever documentações,listas e resumos pois sua estrutura é bem simples.
 Na maioria dos casos o encontramos na raiz do projeto ou seja na pasta principal, pois é nesse arquivo que documentamos peculiaridades do projeto. 
Por padrão escrevemos o README a maioria das vezes com a linguagem markdown a qual utiliza a extensão ( .md ). Também podemos encontrar um arquivo README com outras extensões mas seus princípios sempre serão os mesmos.
Antes de pensar em escrever uma documentação ou melhor um arquivo README, temos que verificar quem serão nossos leitores, assim conseguimos adotar uma metodologia de escrita na qual o leitor irá se identificar melhor.

É comum temos os seguintes leitores para o documentações :

  1. Nós mesmos.
  2. Colegas de trabalho.
  3. Usuários aleatórios da web.
Iremos ver que o arquivo README é bem semelhante a um simples arquivo texto ( .txt ). A simplicidade da escrita do README é pelo fato de que estamos escrevendo para o entendimento de seres-humanos e não de máquinas.. ou seja temos de nos imaginar no lugar do leitor e escrever algo simples porém eficaz e de fácil entendimento.
A nomenclatura README quer dizer ( leia-me ), agora já sabemos que é importante ler esse arquivo sempre que o encontrarmos em algum projeto ou em outras circunstâncias.

Anatomia do arquivo

O README não tem um único padrão de estrutura específico, pois cada projeto tem suas particularidades, tendo em vista que alguns tópicos realmente acabam se adaptando a qualquer tipo de projeto..
Para melhor entendimento, irei fazer algumas perguntas que devem ser feitas antes de escrevermos o arquivo, pois essas perguntas vão determinar o que teremos que escrever no README.

1. Quais são as ordens das etapas a serem executadas para que o código/projeto funcione ??

2. Quais são as pré configuração que precisamos ter ??

3. O que precisa ser instalado ??

4. O que pode ter estar difícil de entender ao ler o código??

5. Temos algum problema no código que pode gerar erro ??

Obtendo um feedback referente a essas perguntas, já podemos escrever um README que seja eficaz e utilizar-lo.


Escrevendo um README bem simples

Já temos uma base de como levantamos informações para escrever uma documentação, já podemos começar escrever um arquivo README tranquilamente…

Agora o trem fica sério !!!

Vamos ver como o README é utilizado na prática e iremos criar um exemplo real de como ele é usado na maioria dos casos.
Primeiramente, será citado os “tópicos” que irão conter no exemplo..

1. Titulo do projeto.

2. Instruções da instalação.

3. Uso comum da ferramenta.

4. Mapeamento de bugs conhecidos.

Abaixo está como ficaria uma estrutura README escrita com markdown, com os tópicos mencionados acima referenciados entre ( ) ..

# ProjectX (1.titulo)

### Instruções (2.instruções da instalação)

- Precisamos ter o nodejs e seu gerenciador de pacotes NPM instalados antes de mais nada..

- Instalar o lite-server, via terminal:

npm install -g lite-server

### Como utilizar a ferramenta (3.uso comum da ferramenta.)

- Basta fazer o clone do repositório da seguinte forma:

git clone https://github.com/teste

- Agora entramos no diretório do projeto que clonamos anteriormente via terminal:

cd teste

- Estando no diretório do projeto, é só levantar um servidor local, via terminal:

lite-server

### Bugs (4.mapeamento de bugs conhecidos)

- Não temos bugs para apresentar até agora, mais encontrarem algum favor mandar um pull request no repositório para verificarmos.

Essa exemplo foi uma estrutura básica referente a uma documentação qualquer, ou seja foi apenas para mostrar o quão simples é. Mais abaixo vou deixar alguns links de algumas documentações bem legais e outros exemplos do uso do arquivo README como por exemplo em uma awesome-list

awesome-list
my-repository
frontend-checklist


Asks

Ué… todo arquivo README que eu encontro esta escrito com caixa alta, qual o motivo disso?

É basicamente para dar uma ÊNFASE no arquivo aos olhos de terceiros, pois lembrar desse arquivo é muito importante pois ele é essencial para documentar seu projeto por menor que ele seja. Sendo assim, basta o leitor passar os olhos no diretório do projeto que contenha um arquivo README que logo de cara ele irá nota-lo, devido sua CAIXA ALTA..
Então resumindo.. a CAIXA ALTA é pra não deixar passar batido aos olhos do usuário ao explorar um diretório que contenha o arquivo README.

Conclusão

Agora já temos uma noção de como se escreve um README simples e funcional e sabemos bem qual é sua finalidade. Daqui pra frente quando vermos um arquivinho chamado README não teremos preguiça de o abrir e tentar entender-lo pois já sabemos que sua importância é CRUCIAL.

Espero sinceramente que esse post ajude algum curioso como eu que decidiu fazer uma pesquisa sobre um assunto tão simples, mas porém não é muito mencionado na maioria dos cursos e conteúdos gratuitos em pt-BR.

Forte abraço, até a próxima =)

Contatos

Github
Instagram
Twitter