Boas práticas para uma documentação markdown de sucesso

O markdown é uma importante linguagem de marcação criada por John Gruber e Aaron Swartz para simplificar a formatação de arquivos XHTML ou HTML a partir de textos simples.

A linguagem vem ganhando cada vez mais popularidade no meio da TI e dos desenvolvedores, já que pode ser usada para simplificar a criação de documentos técnicos para diferentes projetos, como sites, aplicativos e APIs. 

Para que a marcação seja feita corretamente e os arquivos sejam publicáveis sem qualquer tipo de instrução complexa, é importante que os devs aprimorem suas habilidades de documentação e realmente compreendam o que é markdown.

No artigo falamos mais sobre a linguagem markdown e como usá-la na documentação técnica a partir de 10 práticas simples. Boa leitura!  

O que é markdown e como funciona

O markdown é uma linguagem de marcação que armazena texto em arquivos .md ou .markdown. Para transformar esses arquivos em HTML ou formatos imprimíveis é necessário um aplicativo markdown.

Essas ferramentas lêem o texto em formato markdown e o reescrevem no formato HTML. Dessa forma, o documento técnico será facilmente visualizado em um navegador web ou combinado com uma folha de estilos para impressão.

Existem várias opções disponíveis, desde aplicativos de linha de comando até versões baseadas na web.

Os aplicativos markdown e seus processadores desempenham um papel muito importante para a simplificação da formatação de texto. Eles permitem que os usuários criem documentos legíveis, mesmo sem experiência em linguagens de marcação complexas como o HTML.

Por que usar markdown

Existem muitas razões por que a linguagem markdown precisa ser usada pelo time de desenvolvedores. 

A principal é a acessibilidade. A sintaxe direta e intuitiva do markdown, que se baseia em combinações de símbolos simples para formatação, torna a linguagem acessível a todos os usuários, desde os mais técnicos até aqueles com menos experiência. 

O markdown também proporciona independência da plataforma, pois os arquivos podem ser facilmente convertidos para outros formatos (HTML, PDF ou documentos do Word), o que favorece o compartilhamento entre diferentes dispositivos e aplicações.

Outro motivo envolve a legibilidade. Os documentos criados com a linguagem se tornam mais legíveis, pois não incluem as tags complexas presentes no HTML. Isso, além de simplificar a escrita e a compreensão dos conteúdos, permite que as equipes se concentrem em outras atribuições, sem distrações relacionadas à formatação.

Outro ponto interessante é que é possível obter maior controle das versões dos documentos, já que a linguagem facilita o rastreamento das alterações e os usuários podem reverter para versões anteriores, se preciso. 

LEIA TAMBÉM | Versionamento de API: lide com as mudanças de forma estratégica 

10 boas práticas para usar markdown na documentação técnica

Como dito anteriormente, os devs precisam aprimorar suas habilidades de documentação, caso queiram que os arquivos convertidos com markdown sejam publicáveis sem marcações de tags ou instruções de formatação.

Abaixo separamos algumas boas práticas que o ajudam a aplicar a linguagem na documentação técnica da API. Confira! 

1. Use letras maiúsculas em casos de uso de markdown padrão, como é o caso de CHANGELOG.md e README.md;
2. Para manter a organização em repositórios e evitar confusões com a estrutura principal, coloque qualquer documentação “não padrão” em uma pasta fora da raiz.docs;
3. Ao usar blocos de código, especifique o idioma na primeira linha divisória;
4. Inclua a URL completa nos links, incluindo o protocolo (http:// ou https://);
5. Para caracteres que fazem parte da sintaxe markdown, use uma barra invertida antes do caractere para que seu aplicativo não leia esse caractere como formatação;
6. Quando optar por um nome “não padrão”, certifique-se de usar a convenção de nomenclatura camel para os nomes de arquivos. Por exemplo, .docs/meuDocumentoAdicional.md;
7. Mantenha um estilo de escrita consistente para não gerar uma formatação conflitante;
8. Verifique se as tabelas têm o mesmo número de células que a linha de cabeçalho;
9. Lembre-se de incluir parênteses após o nome de uma função em um bloco de código;
10. Use a extensão de arquivo correta ao inserir uma imagem, por exemplo, .jpg ou .png.

Conheça o DHuO API Plus da Engineering  

Entender e dominar a linguagem markdown é uma habilidade que ajuda a equipe de desenvolvedores a criar documentos técnicos bem estruturados e legíveis para os seus projetos de API.

Porém, é importante reconhecer que o sucesso no uso da linguagem não depende apenas da compreensão sobre o que é markdown. A forma de armazenar e controlar toda a documentação também é importante.

O DHuO API Plus é uma plataforma desenvolvida pela Engineering para gerenciar APIs e integrações, que utiliza uma linguagem de marcação simples capaz de formatar o texto com elementos visuais, como por exemplo, cabeçalhos, listas, tabelas, imagens e muito mais. 

O uso desse recurso não apenas complementa a especificação técnica do Open API, mas também possibilita a colaboração entre desenvolvedores e analistas de negócios na construção,  além do entendimento sobre toda a documentação de APIs.Expanda as capacidades de documentação de suas APIs. Conheça o DHuO!