Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 2: Sobre Documentação)
Tags: corda, blockchain, markdown, documentation
Published: 2020-09-17 00:46:25

---
title:  Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 2: Sobre Documentação)
published: true
description: Sobre experimentar com Corda Blockchain
tags: corda, blockchain, markdown, documentation
cover_image: https://media-exp1.licdn.com/dms/image/C5112AQGwT1sMc6Efpw/article-cover_image-shrink_600_2000/0?e=1605744000&v=beta&t=UR1WS3o2-rbKvoUGdipjKhR4255qVsCxaMWIpwuhaS8
---

> “Tem horas em que entender errado é pior do que não entender” **Thiago Grulha**

Nesse terceiro posts sobre [Corda Blockchain](https://www.corda.net/) falaremos sobre o documentação e **README**, uma etapa geralmente negligenciada por nós desenvolvedores.

---

# Para que documentar algo que eu já sei?

Sempre que falo sobre documentação de um conhecimento me lembro do seguinte post que escrevi uma vez em que menciono uma história que o já famoso [Felipe Belluco](https://dev.to/felipebelluco) uma vez me disse:

> Acho interessante que sempre que aprendermos um comando ou algo novo a gente crie uma documentação bem simples.

Isso me trouxe à mente um problema que eu já havia passado com um [Gradle](https://gradle.org/) há um tempo atrás.

Como todo “bom programador”, criei um projeto para testar umas coisas, porém esqueci de versionar…

![Fuê](https://dev-to-uploads.s3.amazonaws.com/i/81a478nhteoqs9nwa2ir.png)

Dias depois, passei pelo mesmo problema que tinha resolvido nesse projeto, fui procurar para ver a solução, e tinha deletado o projeto…

![Fuê-Fuê](https://dev-to-uploads.s3.amazonaws.com/i/ld35th15ru6clh66f53k.png)

---

# Projeto Konami Code

![Konami Code](https://dev-to-uploads.s3.amazonaws.com/i/qq2tg8nuks9vzl2v93hx.jpg)

Acho que todo mundo que já trabalhou com desenvolvimento já se deparou uma vez na vida com a situação de interagir com algo que não se faz a ideia de como simular o ambiente localmente ou como testar uma mudança antes de mandar quilo para produção.

Em um dos clientes que trabalhei, uma frase ficou bem marcada em minha mente:

> “Você sabe como é, aqui na empresa temos vários projetos, mas cada um tem sua ‘manha’ para executar. Ai ficamos perdendo tempo tentando nos lembrar como fazer isso funcionar projeto a projeto”

Chamo esses projetos de **Projetos Konami Code**, precisamos de todo uma abstração, sorte, e execuções dos mais diversos comandos para fazer a solução “subir”.

---

# O time cresceu, problema à vista

Outra problemática dessa abordagem é o crescimento do time… Não vamos conseguir passar tão simples os **Konami Codes** de todos os projetos que ele vai trabalhar, e ai, a gente vira a “própria documentação do código”:

> “Como subo o projeto no **IntelliJ**? Como baixo essa dependência X que não encontro no **Maven Repository**? Meu projeto não compila, o que eu faço?”

Dentre outras perguntas…

A resposta para esses e outros problemas está na documentação do seu projeto.

---

# Mas documentar o que? Tudo?

Na [AIS Digital](https://www.aisdigital.com.br/) trabalhamos com ferramentas para documentação de projeto, porém, é bem interessante saber separar o que deveria ser documentado na página do projeto como um todo, e o que deveria ser documentado em cada repositório.

Aqui não vou trazer nenhuma receita de bolo, o ponto que eu sempre sigo é: documentar o máximo que você achar que é necessário, seja na página do projeto, seja no repositório.

Por exemplo: Um repositório que peguei na [AIS Digital](https://www.aisdigital.com.br/) tinha documentado que para usar o container de um banco em específico era necessário aceitar os termos do mesmo, para podermos baixar a imagem; em outro documentei que em uma abordagem com **API First** era comum que após a geração de classes o projeto continuasse a apresentar erros porque a **IDE** ainda não tinha realizado a indexação das novas classes geradas, sendo necessário um **refresh** para isso.

O ponto aqui é: documente o máximo que tu acha que pode te ajudar a outra pessoa não precisar te mandar email, ligar, mandar **Slack** para saber como interagir com o projeto!

No caso de projetos no **Github**, geralmente tento documentar o máximo de coisas, pois não vou ter ferramentas como [Confluence](https://www.atlassian.com/br/software/confluence), [Sharepoint](https://www.microsoft.com/pt-br/microsoft-365/sharepoint/collaboration) e outras para essa documentação.

Vamos então falar sobre a documentação do nosso repositório no [Github](https://github.com/arthurfnsc/ms-cambio).

---

# Conheça os recursos de Markdown de sua solução de versionamento

[Diana Regina](https://dev.to/dianaops) em um [post](https://dev.to/dianaops/como-escrever-um-readme-md-sensacional-no-github-4509) descreveu com maestria alguns pontos que podem nos ajudar a melhorar a documentação de nosso repositório.

[Filipe Dias](https://www.linkedin.com/in/filipe-dias-633403151/?lipi=urn%3Ali%3Apage%3Ad_flagship3_pulse_read%3BSBHE6JdmRdmTffrG1YifmA%3D%3D), uma vez me mostrou esse [repositório](https://github.com/matiassingers/awesome-readme) também, que pode nos ajudar a escrever **Awesome READMEs**.

Um ponto que os dois tem em comum é chamar a atenção para o suporte a **Markdowns** da solução de versionamento que se deseja usar…

Por exemplo, no caso do [nosso projeto](https://github.com/arthurfnsc/ms-cambio), vocês podem ver que a parte de **Instruções** nos itens **Java 8** e **Gradle (Opcional)** são itens clicáveis que expandem.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/j9w74v3usrehsv9ddhh4.png)

Isso é possível graças a uma **tag HTML** dentro do **README.md**

```

<details><summary><b>Instruções</b></summary>

[Dados a serem ocultados]

</details>

```

E para os mais críticos que acreditam que **Markdown** não deve se misturar com **HTML**, no post **Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 3: Sobre Lint)** além de falarmos sobre **Lint** para **Kotlin**, falaremos sobre um **Lint** para **Markdown**.

Voltando a falar sobre **tags HTML** em **Markdown**, adivinhem então o que aconteceu quando tentei colocar essas mesmas **tags** em um projeto que eu estava participando que não estava no **GitHub** (não me lembro agora se foi no **Bitbucket** ou **GitLab**)?

![Fuê-Fuê-Fuê](https://dev-to-uploads.s3.amazonaws.com/i/a0sa8t4vdortjcxirr4s.png)

Descobri que existia diferença entre interpretadores de **Markdown** de acordo com a solução de versionamento:

* [Bitbucket](https://confluence.atlassian.com/bitbucketserver/markdown-syntax-guide-776639995.html)
* [GitHub](https://guides.github.com/features/mastering-markdown/)
* [GitLab Community Edition](https://docs.gitlab.com/ce/user/markdown.html)

Em alguns deles você possui, inclusive, **tags** especiais, como **[TOC]** (**Table of Contents**). Essa **tag** cria um índice do seu projeto, e para tanto, cada cabeçalho irá se tornar um item com uma âncora de acesso “linkada”.

Sendo assim, uma dica é conheça o que você tem em mãos para facilitar sua documentação.

---

# Executando o projeto

Quando pensei em documentar o nosso projeto, pensei em algumas informações e comandos como:

* Obrigatoriedade do **Java 8**, incluindo um [ponto importante para testes](https://github.com/arthurfnsc/ms-cambio/tree/feature/flow-tests#erros-ao-rodar-os-testes) (que ainda não fiz o **merge** por conta da competição que estou participando, e por esse **commit** ter acontecido depois da data de entrega; esse **merge** pode ter sido realizado dependendo de quando você esteja vendo esse artigo, procure pela seção **Erros ao rodar os testes**);
* Não obrigatoriedade de **Gradle** instalado na máquina para execução do projeto;
* Como clonar o projeto;
* Como gerar os nodes;
* Como rodar os nodes;
* Como executar a “aplicação do banco” e a “aplicação da corretora”
* Dentre outras tasks importantes

Uma vez que o projeto é público, a ideia é tornar mais simples para outras pessoas interagirem com ele e poderem dar feedbacks de melhorias.

---

# Plugins Gradle de documentação

Sobre a parte de documentação, também podemos usar plugins do Gradle. No nosso projeto, os utilizados para documentar estão descritos no arquivo **plugins/docs.gradle**. Mais sobre como utilizar plugins você pode ver em: **Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 1: Sobre Gradle)**.

O [Dokka](https://github.com/Kotlin/dokka) gera a documentação de cada projeto contido no nosso repositório. Nesse caso, dentro do **build** de **application/cordapp-contracts-states**, **application/cordapp-flows** e **application/rest-api** é possível ver uma pasta **dokka** com um **HTML** de nossas classes. Ainda preciso configuração a agregação de todos os relatórios para o **build** da raiz.

O [Project-Report](https://docs.gradle.org/current/userguide/project_report_plugin.html) está mais focado em relatórios de **dependências de projeto** e **tasks de projeto**.

O [Gradle-Versions](https://github.com/ben-manes/gradle-versions-plugin) é um cara tão fera que resolvi dar para ele um post exclusivo, falaremos sobre ele em **Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 4: Sobre Versões Desatualizadas de dependências)**.

---

# Gitm😜ji e Gitm😜ji-Changelog

Utilizei [Gitm😜ji](https://gitmoji.carloscuesta.me/) para meus **commits** serem mais assertivos. A ideia é que uma pessoa pelo emoji tenha ideia do que o **commit** se propõe a fazer, para não precisar clicar em **commit** por **commit** para analisar.

A proposta é ter um **commit** por ação, para não ficar naqueles **commits** que alteram tudo no projeto e tu já nem controla mais isso depois. O uso de **squash** e **rebase** funcionam de forma linda com esse cara!

Um outro cara bem fera que pretendo usar é [Gitm😜ji-Changelog](https://github.com/frinyvonnick/gitmoji-changelog), ele agrega seus **commits** por **tags** e facilita a geração de **changelog**.

---

No demais é isso… nos encontraremos no próximo post em que falarei sobre como iniciei minha jornada com **Kotlin** e como um bom **Lint** é (quase) tudo o que precisamos para aprender uma linguagem nova.

E você tem alguma consideração sobre **README** ou documentação de repositórios, e quer trocar uma ideia? Só bora…

Esse post faz parte de uma série sobre **Corda Blockchain**.

A série completa é:

* [Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Introdução)](https://dev.to/arthurfnsc/corda-blockchain-desafio-r3-pensamentos-sobre-minha-metodologia-de-aprender-algo-novo-introducao-4jnb)
* [Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 1: Sobre Gradle)](https://dev.to/arthurfnsc/corda-blockchain-desafio-r3-pensamentos-sobre-minha-metodologia-de-aprender-algo-novo-parte-1-sobre-gradle-48c3)
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 2: Sobre Documentação)
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 3: Sobre Lint) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 4: Sobre Versões Desatualizadas de dependências) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 5: Sobre Vulnerabilidades de dependências) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 6: Sobre Github flow) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 7: Sobre desenvolvimento em Corda) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 8: Sobre testes em Corda) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 9: Sobre AssertJ) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 10: Sobre testes de arquitetura) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 11: Sobre testes de mutantes) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 12: Sobre JaCoCo) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 13: Sobre SonarQube) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 14: Sobre API First e OpenAPI 3) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 15: Sobre Springboot) [não publicado]
* Corda Blockchain | Desafio R3 — Pensamentos sobre minha metodologia de aprender algo novo (Parte 16: Sobre Mapstruct) [não publicado]

---

Esse artigo foi escrito ouvindo-se **Afterimage | Unveil the Unseen**

{% spotify spotify:album:4sJVyiNvyXB00TfUsKeqHY %}


Original post published at [Medium](https://medium.com/@arthurfnsc/corda-blockchain-desafio-r3-pensamentos-sobre-minha-metodologia-de-aprender-algo-novo-parte-2-ef1cf2adef7c) on September 16th, 2020.