Pular para o conteúdo principal

Verba Volant

Doc as code: Uma introdução

/2025/04/10/doc-as-code-uma-introdu%C3%A7%C3%A3o/ Mauro Abner
Sumário

1. Documentação é importante

Uma boa documentação técnica é crucial tanto para quem dá suporte quanto para o usuário final. Para o suporte, a documentação facilita o processo de resolução de problemas, pois fornece informações precisas e concisas sobre o produto ou serviço. Isso significa que os técnicos de suporte podem resolver problemas mais rapidamente e com mais eficiência, reduzindo o tempo de espera para os clientes. Além disso, a documentação bem estruturada ajuda a evitar a repetição de perguntas frequentes, liberando os técnicos para lidar com problemas mais complexos.

Para o usuário final, a boa documentação permite que ele encontre as informações que precisa de forma rápida e fácil, sem a necessidade de entrar em contato com o suporte. Isso significa maior autonomia e independência para o usuário, que pode resolver problemas simples por conta própria, como configurar o produto, instalar drivers ou solucionar erros básicos. A documentação também pode servir como guia de referência, ajudando o usuário a aproveitar ao máximo os recursos do produto ou serviço.

Em resumo, a documentação técnica de qualidade beneficia tanto o suporte quanto o usuário final, tornando a experiência com o produto ou serviço mais eficiente e satisfatória para todos.

Uma boa documentação, pode servir até de base para treinar um robô-piloto.

Robô treinado com manual simulando piloto de avião

Fonte: GizmodoBR, KAIST e Euronews

2. O que é Doc as Code

Em poucas palavras: Doc as Code [1] trata-se de uma filosofia na qual passamos a escrever documentação da mesma maneira como códigos-fonte são escritos.

Estamos falando de aproveitar processos e ferramental já consagrados na área de programação e levá-los ao mundo da documentação, e neste interim aplicaremos conceitos como:

  • Gerenciamento de incidentes (issue tracker)

  • Controle de versionamento (Version Control)

  • Linguagem de marcação leve (lightweight markup language (LML))

  • Revisão de Código (Code Review)

  • Testes automatizados (Automated Tests)

  • Editor de código-fonte (source-code editor)

E o propósito disto é integração. Seguir o mesmo fluxo de trabalho das equipes de desenvolvimento e, criar uma cultura onde engenheiros (engineers), desenvolvedores (developers, devs) e redatores técnicos (technical writers) trabalhem integrados e sintam-se proprietários da documentação.

3. Explicando os conceitos

  1. Rastreabilidade e Transparência:

    • Issue Tracker ( Gerenciamento de incidentes ): Centralize o registro de problemas, sugestões e feedback na documentação, facilitando a organização e o acompanhamento.

    • Version Control (Controle de Versionamento ): Acompanhe as modificações na documentação com granularidade, permitindo reverter alterações, analisar histórico e colaborar com mais eficiência.

  2. Consistência e Qualidade:

    • Plain Text Markup (Marcação em Texto Simples): Crie documentação em formato de texto simples, com marcação leve para formatação consistente e legível em qualquer plataforma.

    • Code Reviews (Revisão de código) Aplique o mesmo rigor de revisão de código à documentação, garantindo clareza, precisão e coerência com o código-fonte.

  3. Automatização e Integração:

    • Automated Tests (Testes automatizados): Valide automaticamente a documentação para garantir que esteja completa, atualizada e livre de erros, economizando tempo e aumentando a confiabilidade.

    • Integração com Ferramentas: Conecte o "Doc as Code" ao seu fluxo de trabalho de desenvolvimento, automatizando a geração de documentação a partir do código-fonte.

4. CI/CD para Doc as Code

O CI/CD (Continuous Integration and Continuous Delivery) é uma prática de desenvolvimento de software que visa automatizar o ciclo de vida do desenvolvimento à entrega. No contexto do Doc as Code, o CI/CD pode ser usado para automatizar a criação, atualização e entrega da documentação.

Etapas do Processo:

  1. Integração Contínua:

    • A cada modificação no código-fonte ou na documentação, o código é verificado e testado.

    • Se os testes forem bem-sucedidos, a documentação é gerada e armazenada em um repositório central.

  2. Entrega Contínua:

    • A documentação gerada é automaticamente publicada em um canal de distribuição, como um site ou portal de documentação.

    • A equipe pode definir gatilhos específicos para a entrega, como a criação de uma nova versão do software.

5. Como começar a escrever utilizando Doc as Code

5.1. Introdução

É importante ressaltar que este artigo não explicará na prática o uso do Git e Github Action, que são ferramentas essenciais para realizar o CI/CD para Doc as Code.

Neste artigo nos ateremos ao uso da linguagem de marcação para documentar. E esta abordagem foi propositalmente escolhida, por que em uma busca rápida no YouTube é possível aprender sobre Git e Github Action, porém não posso dizer o mesmo sobre o tema linguagem de marcação leve. Pelo menos até o momento da escrita desse artigo.

5.2. Linguagens de Marcação

Particularmente acredito que a primeira etapa para iniciar a escrever documentação, implementando a filosofia Doc as Code, é entender o que é uma linguagem de marcação (markup language).

É preciso entender que a única forma que existe para fazer com que um software possa processar o cabeçalho (header) de um documento como "o cabeçalho do documento", é de alguma forma indicando que aquele é "o cabeçalho do documento".

Para deixar isto mais claro, vamos pegar o texto clássico de Gênesis 1:

Gênesis 1

No princípio, Deus criou os céus e a terra. A terra era sem forma e vazia, a escuridão cobria as águas profundas, e o Espírito de Deus se movia sobre a superfície das águas.

Como faríamos para que um software processasse essa informação como "Gênesis 1" sendo o cabeçalho (header), isto é, o título número 1, e o restante do texto, como um paragrafo simples?

Página HTML sem marcações
Figure 1. Navegador processando uma página escrita em texto sem marcações

Bom, a resposta para isso é colocarmos algumas marcações (markups) para indicar isso.

<Início do Título 1> Gênesis 1 <Fim do Título 1>

<Início do Parágrafo> No princípio, Deus criou os céus e a terra. A terra era sem forma e vazia, a escuridão cobria as águas profundas, e o Espírito de Deus se movia sobre a superfície das águas. <Fim do Parágrafo>

Mas não pode ser qualquer marcação, deve existir uma padronização, de forma com que todos os softwares consigam identificar o que determinada marcação quer dizer sobre o conteúdo que se está marcando.

Para que isso aconteça, existem algumas convenções de como podemos fazer marcações, e uma das mais usadas no mundo da internet é a Linguagem de Marcação de Hipertexto (Hypertext Markup Language (HTML)) [2] [3].

Optando-se por usar a HTML, o trecho de Gênesis 1 acima seria escrito assim:

<h1> Gênesis 1 </h1>

<p> No princípio, Deus criou os céus e a terra. A terra era sem forma e vazia, a escuridão cobria as águas profundas, e o Espírito de Deus se movia sobre a superfície das águas. </p>

Deste modo, quando esse trecho for processado por um software chamado navegador (browser), o navegador organizará e exibirá essas informações em uma determinada ordem, e com uma determinada formatação, pois agora há instruções de que "Gênesis 1" é um título de nível 1, e "No princípio, Deus criou…​" é um parágrafo simples.[4][5]

Página HTML com marcações
Figure 2. Navegador processando uma página com texto escrito com HTML

No entanto, ao longo do tempo percebeu-se que escrever longos documentos utilizando HTML, não era uma tarefa simples e ágil, pois as marcações da HTML não facilitavam nem a escrita e nem legibilidade do texto.

Para visualizar a HTML de qualquer página no seu navegador, você pode usar o seguinte procedimento: basta abrir um site no seu navegador e utilizar os comandos Ctrl + U (Windows) ou Command + U (Mac). Isto deve funcionar para a maioria dos navegadores.

E numa busca para tornar a tarefa de escrever e revisar publicações menos árduas, surgiram as linguagem de marcação leve (lightweight markup language (LML)).

5.3. Linguagem de Marcação Leve (LML)

Linguagens de marcação leve (lightweight markup language (LML)) surgem como um meio mais ágil e fácil para escrever e ler textos que serão processados por um software.

Pensando-se no mundo da WEB, estas linguagens não substituem a HTML, pois HTML é o padrão usado e aceito por todos os navegadores, contudo podemos escrever com elas por um principio bem simples: Existem softwares [6] que convertem linguagens de marcação leve em HTML, e não somente HTML mas também, PDF [7], EPUB [8], LaTeX [9] etc…​ Um software de conversão normalmente é chamado de processador de texto (text processor), ou somente processador (processor)[10]. E um processador pode ser escrito por desenvolvedores em diversas linguagem de programação, como Python, Ruby, Javascript, etc…​de acordo com a necessidade do time de devs que decidiu se dedicar a esta tarefa.

Página HTML com marcações
Figure 3. Ilustração do processo de conversão

Existem diversas linguagens de marcação leve, porém neste texto citarei apenas três, e das três me aprofundarei apenas em uma: Asciidoc.

As três LML são:

  • Markdown

  • reStructuredText

  • Asciidoc

5.3.1. Markdown

Markdown [11] é uma linguagem de marcação leve extremamente popular para escrita de conteúdo para internet, sua simplicidade a fizeram ganhar o coração de muita gente. No entanto ela não possuí uma padronização definitiva, existindo variações, conhecidas como sabores (flavours) de sintaxe, isto é, formas de como escrever com Markdown. Entre os sabores mais conhecidos, temos:

  • CommonMark [12]

  • GitHub Flavored Markdown [13]

Vou fazer aqui uma menção ao MyST [14]. Este flavour não é tão conhecido, mas trata-se de uma iniciativa interessante de pensar um flavour Markdown voltado para escrita de documentação técnica e científica.

Não vamos nos aprofundar muito na Markdown, mas para efeito de comparação, veja o parágrafo escrito em HTML:

<h1> Gênesis 1 </h1>

<p> No princípio, Deus criou os céus e a terra. A terra era sem forma e vazia, a escuridão cobria as águas profundas, e o Espírito de Deus se movia sobre a superfície das águas. </p>

E o mesmo parágrafo escrito em Markdown:

# Gênesis 1

No princípio, Deus criou os céus e a terra. A terra era sem forma e vazia, a escuridão cobria as águas profundas, e o Espírito de Deus se movia sobre a superfície das águas.

Perceba que as marcações <h1> </h1> foram substituída por somente uma cerquilha #, e as marcações <p></p> não aparecem, pois serão subentendidas pelo processador.

Para saber mais sobre como escrever em Markdown (a sintaxe da linguagem) e os processadores de texto que existem para essa LML, acesse: https://www.markdownguide.org/

5.3.2. reStructuredText

reStructuredText é uma linguagem de marcação leve com propósito principal de servir como uma meio para se escrever Python docstrings [15][16] e outros tipos de documentos em todo o ecossistema de documentação para projetos que envolvam Python. Apesar de não ser restrita a este universo, seu uso mais amplo é este.

Não vamos nos aprofundar muito na reStructuredText, mas para efeito de comparação, veja o parágrafo escrito em HTML:

<h1> Gênesis 1 </h1>

<p> No princípio, Deus criou os céus e a terra. A terra era sem forma e vazia, a escuridão cobria as águas profundas, e o Espírito de Deus se movia sobre a superfície das águas. </p>

E o mesmo parágrafo escrito em reStructuredText:

=========
Gênesis 1
=========

No princípio, Deus criou os céus e a terra. A terra era sem forma e vazia, a escuridão cobria as águas profundas, e o Espírito de Deus se movia sobre a superfície das águas.

Perceba que as marcações <h1> </h1> foram substituída pelo carácter = acima (overline) e abaixo (underline) ao texto Gênesis 1. As marcações <p></p> não aparecem, pois serão subentendidas pelo processador.

5.3.3. Asciidoc

Asciidoc é uma linguagem de marcação leve pensada para escrita de livros, artigos, documentação técnica etc…​. Possuí sintaxe padronizada [17] e foi projetada pensado-se na publicação tanto impressa quanto online, além da máxima reutilização do conteúdo.

Apesar de ser mais robusta que a markdown[18], é tão simples quanto esta, tendo fácil escrita e grande legibilidade.

O padrão de sintaxe da Asciidoc pode ser aprendida neste link: https://docs.asciidoctor.org/asciidoc/latest/

Mas se você precisar de um guia rápido para a sintaxe Asciidoc, pode acessá-lo aqui: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/
Processadores de Texto para Asciidoc

Para que se possa publicar nos diversos formatos que a linguagem Asciidoc permite, são necessário processadores de textos específicos criados para cada tipo de publicação.

Podemos listar alguns:

  • Asciidoctor [19]

    É um processador (processor) escrito em linguagem de programação Ruby [20] que pode analisar (parsing), interpretar (interpret) e converter (convert) um documento escrito em Asciidoc para HTML5.

  • Asciidoctor.js [21]

    Este é um projeto que converteu os processador Asciidoctor escrito em Ruby para um processador escrito em Javascript. A vantagem desta conversão é que permitiu que o Asciidoctor pudesse ser executado por qualquer navegador web.

  • Asciidoctor PDF [22]

    É o processador Asciidoctor, ainda escrito em Ruby, mas com a capacidade de converter um documento escrito em Asciidoc para PDF.

  • Asciidoctor EPUB3 [23]

    É o processador Asciidoctor, ainda escrito em Ruby, mas com a capacidade de converter um documento escrito em Asciidoc para EPUB3.

5.3.4. Escrevendo em Asciidoc

  1. PASSO 1

    Para primeira experiência de escrever em Asciidoc, vamos pegar a constituição do Brasil de 1988 [24] em texto simples, ao menos os quatro primeiros artigos, sem nenhuma formatação de texto, e vamos colá-los no Bloco de Notas do Windows, ou qualquer editor de texto simples.

    CONSTITUIÇÃO DA REPÚBLICA FEDERATIVA DO BRASIL DE 1988
PREÂMBULO

Nós, representantes do povo brasileiro, reunidos em Assembléia Nacional Constituinte para instituir um Estado Democrático, destinado a assegurar o exercício dos direitos sociais e individuais, a liberdade, a segurança, o bem-estar, o desenvolvimento, a igualdade e a justiça como valores supremos de uma sociedade fraterna, pluralista e sem preconceitos, fundada na harmonia social e comprometida, na ordem interna e internacional, com a solução pacífica das controvérsias, promulgamos, sob a proteção de Deus, a seguinte CONSTITUIÇÃO DA REPÚBLICA FEDERATIVA DO BRASIL..

TÍTULO I

Dos Princípios Fundamentais

 Dos Princípios Fundamentais

Art. 1º A República Federativa do Brasil, formada pela união indissolúvel dos Estados e Municípios e do Distrito Federal, constitui-se em Estado Democrático de Direito e tem como fundamentos:

I - a soberania;

II - a cidadania

III - a dignidade da pessoa humana;

IV - os valores sociais do trabalho e da livre iniciativa;

V - o pluralismo político.

Parágrafo único. Todo o poder emana do povo, que o exerce por meio de representantes eleitos ou diretamente, nos termos desta Constituição.

Art. 2º São Poderes da União, independentes e harmônicos entre si, o Legislativo, o Executivo e o Judiciário.

Art. 3º Constituem objetivos fundamentais da República Federativa do Brasil:

I - construir uma sociedade livre, justa e solidária;

II - garantir o desenvolvimento nacional;

III - erradicar a pobreza e a marginalização e reduzir as desigualdades sociais e regionais;

IV - promover o bem de todos, sem preconceitos de origem, raça, sexo, cor, idade e quaisquer outras formas de discriminação.

Art. 4º A República Federativa do Brasil rege-se nas suas relações internacionais pelos seguintes princípios:

I - independência nacional;

II - prevalência dos direitos humanos;

III - autodeterminação dos povos;

IV - não-intervenção;

V - igualdade entre os Estados;

VI - defesa da paz;

VII - solução pacífica dos conflitos;

VIII - repúdio ao terrorismo e ao racismo;

IX - cooperação entre os povos para o progresso da humanidade;

X - concessão de asilo político.

Parágrafo único. A República Federativa do Brasil buscará a integração econômica, política, social e cultural dos povos da América Latina, visando à formação de uma comunidade latino-americana de nações.

    Agora, vamos abrir o link do guia rápido para a sintaxe Asciidoc : https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

    Sempre mantenha o guia rápido para a sintaxe Asciidoc em mãos. Fazer isto facilitará bastante sua escrita.

  2. PASSO 2

    Feito isto, vamos aplicar a sintaxe que comunica melhor o que queremos mostrar ao leitor.

    = CONSTITUIÇÃO DA REPÚBLICA FEDERATIVA DO BRASIL DE 1988
:toc: left
:homepage: https://www.planalto.gov.br/ccivil_03/constituicao/constituicao.htm

== PREÂMBULO

Nós, representantes do povo brasileiro, reunidos em Assembléia Nacional Constituinte para instituir um Estado Democrático, destinado a assegurar o exercício dos direitos sociais e individuais, a liberdade, a segurança, o bem-estar, o desenvolvimento, a igualdade e a justiça como valores supremos de uma sociedade fraterna, pluralista e sem preconceitos, fundada na harmonia social e comprometida, na ordem interna e internacional, com a solução pacífica das controvérsias, promulgamos, sob a proteção de Deus, a seguinte CONSTITUIÇÃO DA REPÚBLICA FEDERATIVA DO BRASIL.

== TÍTULO I
=== Dos Princípios Fundamentais

.Art. 1º
A República Federativa do Brasil, formada pela união indissolúvel dos Estados e Municípios e do Distrito Federal, constitui-se em Estado Democrático de Direito e tem como fundamentos:

[upperroman]
. a soberania;
. a cidadania;
. a dignidade da pessoa humana;
. os valores sociais do trabalho e da livre iniciativa;
. o pluralismo político.

_Parágrafo Único._ Todo o poder emana do povo, que o exerce por meio de representantes eleitos ou diretamente, nos termos desta Constituição.

.Art. 2º
São Poderes da União, independentes e harmônicos entre si, o Legislativo, o Executivo e o Judiciário.

.Art. 3º
Constituem objetivos fundamentais da República Federativa do Brasil:

[upperroman]
. construir uma sociedade livre, justa e solidária;
. garantir o desenvolvimento nacional;
. erradicar a pobreza e a marginalização e reduzir as desigualdades sociais e regionais;
. promover o bem de todos, sem preconceitos de origem, raça, sexo, cor, idade e quaisquer outras formas de discriminação.

.Art. 4º
A República Federativa do Brasil rege-se nas suas relações internacionais pelos seguintes princípios:

[upperroman]
. independência nacional;
. prevalência dos direitos humanos;
. autodeterminação dos povos;
. não-intervenção;
. igualdade entre os Estados;
. defesa da paz;
. solução pacífica dos conflitos;
. repúdio ao terrorismo e ao racismo;
. cooperação entre os povos para o progresso da humanidade;
. concessão de asilo político.

_Parágrafo Único._ A República Federativa do Brasil buscará a integração econômica, política, social e cultural dos povos da América Latina, visando à formação de uma comunidade latino-americana de nações.

    Se você observar com cuidado, nós basicamente usamos:

    E outros detalhes menores que você pode encontrar lendo a documentação oficial.

  3. PASSO 3

    Salve o arquivo com o texto da Constituição, formatado de acordo com a sintaxe Asciidoc, na sua área de trabalho com a extensão .adoc.

    Você pode nomear o arquivo como: contituicao.adoc

  4. PASSO 4

    Agora vamos abrir este o arquivo .adoc com o processador de texto adequado. Para esta etapa, afim de facilitar o processo, vamos instalar a extensão Asciidoctor para navegador (Asciidoctor Browser Extension)[25] chamada Asciidoctor.js Live Preview.

    Esta extensão trata-se de um visualizador de arquivos asciidoc (AsciiDoc File Viewer) que usa o processador Asciidoctor.js .
    Neste tutorial usaremos o navegador Microsoft Edge, porém não há muita diferença no procedimento caso se use outro navegador. Para mais informações acesse: https://docs.asciidoctor.org/browser-extension/install/ .

    Portanto, clique na imagem abaixo, ou busque na Web Store do seu navegador, pela extensão Asciidoctor.js Live Preview, e a instale.

    Imagem da loja de extensões do Microsoft Edge
    Figure 4. Web Store do Microsoft Edge

  5. PASSO 5

    Para que a a extensão Asciidoctor.js Live Preview, instalada no seu navegador Microsoft Edge, possa visualizar arquivos no seu computador, é necessário conceder à extensão acesso ao computador. Para isso, siga os seguintes passos.

    1. Digite a URL chrome://extensions e pressione ENTER.

    2. Digite asciidoctor da barra de pesquisar extensões instaladas.

    3. Assim que a extensão Asciidoctor.js Live Preview aparecer, clique em Detalhes.

    4. Marque:

      • Permitir acesso a URLs de arquivos

    5. Feche o navegador.

  6. PASSO 6

    Existem duas formas de abir o arquivo contituicao.adoc no navegador Microsoft Edge:

    OPÇÃO 1

    Abra o navegador e clique, segure e arraste o arquivo contituicao.adoc para dentro do navegador.
    OPÇÃO 2

    Clique com o botão direito do mouse sobre o arquivo contituicao.adoc e selecione Abrir com e, escolha abrir com o Microsoft Edge.
    Certifique-se que a extensão Asciidoctor.js Live Preview está ativada.

    Para ativar ou desativar a extensão Asciidoctor.js Live Preview, basta clicar na logo do Asciidoctor Logo do Asciidoctor dentre as extensões do seu navegado.

6. Editor de Código-Fonte

Deixei este tópico por último, pois para o trabalho que nos propusemos a fazer neste artigo, não era crucial ter um editor de código-fonte ( source-code editor ) [26] ou uma IDE [26], no entanto, ter uma dessas ferramentas, facilita muito a escrita em linguagem de marcação leve, por isso gostaria de deixar algumas dicas sobre como usar um editor.

Teste tanto o VSCode quanto o IntelliJ IDEA Community edition, e avalie qual te atenderá melhor.

6.1. VSCode

O VSCode é um editor de code-fonte que é de uso livre tanto individual quanto para organizações.[27]

Caso o VSCode ainda não estiver instalado, instale-o com o seguinte link: https://code.visualstudio.com/download

Após instalação do VSCode, instale as seguintes extensões:

E pronto, o VSCode já está pronto para ser usado para se escrever documentos em Asciidoc.

6.2. IntelliJ IDEA Community edition

O IntelliJ IDEA Community edition é uma IDE, e portanto, possui mais recursos no que tange ferramentas para programação no geral. E também, possui uma extensão, isto é, plugin baste robusto para se trabalhar com com Asciidoc. Além disso é de uso livre tanto individual quanto para organizações.[28]

Caso o IntelliJ IDEA Community edition ainda não estiver instalado, instale-o com o seguinte link: https://www.jetbrains.com/idea/download/

Tenha certeza que você está fazendo download e instalado a versão IntelliJ IDEA Community, pois somente esta versão é de uso livre.

Após instalação do IntelliJ IDEA Community edition, instale o seguinte plugin: https://plugins.jetbrains.com/plugin/7391-asciidoc

E pronto, o IntelliJ IDEA Community já está pronto para ser usado para se escrever documentos em Asciidoc.

FIM ■

1. https://www.writethedocs.org/guide/docs-as-code/
2. Para obter um histórico da HTML acesse https://html.spec.whatwg.org/#history-2 .
3. Para aprender mais sobre HTML acesse https://developer.mozilla.org/pt-BR/docs/Web/HTML
4. A primeira página Web era bem simples, você pode visitá-la em http://info.cern.ch/hypertext/WWW/TheProject.html
5. Para um histórico sobre a Web, acesse: https://home.cern/science/computing/birth-web
6. Este é um projeto open source que são praticamente um canivete suíço da conversão entre documentos: https://pandoc.org/
7. https://www.iso.org/standard/75839.html
8. https://www.w3.org/publishing/groups/epub-wg/
9. https://www.latex-project.org/
10. Poder ser que em alguns lugares você encontre o nome parser ou transpiler
11. Este é o site onde o Markdown foi originalmente proposto: https://daringfireball.net/projects/markdown/
12. Acesse: https://commonmark.org/
13. Acesse: https://github.github.com/gfm/
14. Acesse: https://myst-parser.readthedocs.io/en/latest/
15. https://en.wikipedia.org/wiki/Docstring
16. https://peps.python.org/pep-0257/
17. Para ver o escopo do projeto, acesse: https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/process/scope.adoc
18. Para uma comparação entre as duas linguagens, acesse: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/
19. Para informações sobre este processador, acesse: https://docs.asciidoctor.org/asciidoctor/latest/
20. Para mais informações, acesse: https://www.ruby-lang.org/pt/
21. Para informações sobre este processador, acesse: https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/
22. Para informações sobre este processador, acesse: https://docs.asciidoctor.org/pdf-converter/latest/
23. Para informações sobre este processador, acesse: https://docs.asciidoctor.org/epub3-converter/latest/
24. https://www.planalto.gov.br/ccivil_03/constituicao/ConstituicaoCompilado.htm
25. Para mais informações, acesse: https://docs.asciidoctor.org/browser-extension/
26. Um source-code editor é uma ferramenta leve focada na escrita e edição de código, com funcionalidades básicas como realce de sintaxe e autocompletar. Um IDE é uma plataforma completa que integra várias ferramentas, incluindo depuração, compilação e controle de versão, oferecendo suporte ao ciclo completo de desenvolvimento de software. Em geral, editores são mais leves e rápidos, enquanto IDEs são mais robustos e abrangentes. São editores: Sublime Text, Visual Studio Code, Atom, Notepad++. São IDE’s: IntelliJ IDEA, Eclipse, PyCharm, Visual Studio.
27. Para mais informações, acesse https://code.visualstudio.com/license
28. Para mais informações, acesse https://sales.jetbrains.com/hc/en-gb/articles/360021922640-Can-I-use-Community-Editions-of-JetBrains-IDEs-for-developing-commercial-proprietary-software