Boas Práticas pra Documentos em Markdown
Assim como testes unitários, não vejo muita gente comentando sobre a importância de se mantar uma boa documentação de projetos, sendo que o README é, provavelmente, a primeira coisa que vemos quando sabemos sobre um projeto novo. Então eu fiz uma pesquisa bem superficial, porém ainda relevante, sobre os guias que a Google recomenda que os desenvolvedores sigam na hora de escrever alguma documentação. E eu concordo com grande parte do que eu li no repositório de estilos deles, então cá estou eu pra dividir o que aprendi sobre detalhes de como escrever e estruturar documentos em Markdown com vocês.
Tabela de conteúdos:
Boas Práticas pra Documentos em Markdown
Sem entrar em detalhes da história da linguagem, é bom ter em mente que o Markdown foi criado com a única intenção de ser um "HTML melhorado", com uma sintaxe bem mais amigável, e que no final do dia pode ser convertido pra um documento em HTML. Mas esse "melhor" – ao menos pra documentos mais focados em conteúdo textual, como artigos de blogs, essays e relatórios – não se trata somente de performance/produtividade durante a escrita, a principal feature do Markdown é a sua legibilidade do código fonte.
Muitas vezes, os desenvolvedores irão precisar fazer algum tipo de manutenção nas documentações de algum projeto, ou só conferir uma coisa rápido pelo o editor de código. De qualquer forma, não é incomum lidar com o código fonte (não formatado) de um documento em Markdown, portanto, o autor do documento precisa ter isso em mente e tomar algumas medidas práticas pra que o documento fique legível mesmo sem ter sido formatado pra HTML.
Escrevendo Markdown Semântico
De forma geral, a ideia é usar de espaços e alinhamento pra tornar as coisas legíveis. Abaixo vou deixar as convenções que eu costumo seguir quando preciso escrever alguma documentação no Github (não são regras), cheque os README's dessa ferramenta que fiz pra uma amiga e desse projeto pra ver essa lista sendo usada na prática.
- Limite as linhas pra ter, no máximo, 80 caracteres. Linhas muito compridas são difíceis de ler; a única coisa que incomoda são os links, tente deixar eles na mesa linha do texto e só passe pra próxima se não couber mais nada depois do link.
- Parágrafos e títulos devem ser separados por uma linha vazia. Não deixe os títulos grudados no parágrafo, pule uma linha depois do título; imagens devem estar em seu próprio parágrafo e listas podem ser agrupadas por parágrafo também.
- Não use tabelas. São super irritantes de se lidar, principalmente quando o editor não ajuda, em quase todo senário dá hierarquia de listas no lugar de tabelas.
- Minimize dependências (imagens e links). Um documento bem escrito deve fazer sentido só com o conteúdo textual nele, imagens devem ser um apoio adicional, não uma obrigatoriedade.
- Tente usar texto puro. Ou seja, tente escreva em inglês e não use emojis, esses caracteres estranhos podem causar problemas no editor de alguém de outro país, inglês é o padrão.
E outra – talvez até o mais importante –, não use HTML em um documento escrito em Markdown! A única rasão pra você querer usar HTML dentro de um arquivo .md é puramente por estilo, e estilo não deve ser uma preocupação ao escrever um documento. Além de ser um desrespeito com a linguagem em si, dificulta bastante a leitura.
Mas entenda, nada disso são regras que devem ser seguidas estritamente, são apenas recomendações, se alguma dessas regras prejudica a legibilidade é obrigação sua por o peso das decisões na balança e escolher a que é mais vantajosa pra ti. Apenas tenha em mente que todo documento serve pra um propósito diferente.
Como Organizar as Informações
Algo que é universal pra todo tipo documento é o fato de que ele precisa ser direto ao ponto, não necessariamente curto, mas simples e só com as informações necessárias pra resolver o tipo de problema que esse documento quer resolver. É bom que o título de nível 1 – famoso <h1> – tenha um nomo similar ao nome do arquivo, seguido de uma breve descrição TL;DR1 e, se conveniente, uma árvore de tópicos (TOC2) pra facilitar a navegação; daí que vem o conteúdo do documento, começando com um título de nível 2.
E é de boa educação também colocar um tópico no final com o título "See also" ou "References", pra ter um lugar onde listar as referências de pesquisas e guiar o leitor pra outras fontes de conteúdo caso queira se aprofundar.
README.md
No caso de um README.md de um projeto de desenvolvedor é bom levar em conta que o README, provavelmente, será o primeiro contato do usuário, ou de um novo membro do time, com o projeto em particular. Então é importante que esse arquivo sirva como um guia inicial e traga as informações mais importantes logo de cara.
O ideal é que ele seja curto mesmo, amigável à leitura dinâmica, com exemplos descritivos de como rodar o projeto ou contribuir. Mas se ficar muito detalhado é comum separar em arquivos menores e mais específicos como um STYLE_GUIDE.md pra definir estilos de código e boas práticas ou um CONTRIBUITING.md com instruções de como rodar o projeto em ambiente de desenvolvimento.
Eu só trabalhei em projeto pequeno, então um README curtinho na raíz do projeto já serve, mas a ideia tradicional de um arquivo README é ser uma descrição do diretório em que ele está situado, então acredito que seja bom ter um documento desse tipo nos diretórios de módulos, testes, etc., caso seja necessário.
Mais Informações
Eu vou postar esse artigo no meu blog pessoal futuro – eu basicamente compiei tudo na íntegra das minhas anotações –, então qualquer sujestão, ideia ou comentário sobre o assunto poderá servir de material pra mim, conto com o apoio de vocês!
Documentos que extraí informação pra escrever isso:
E pra quem quer gerar um TOC bonitinho também, eu achei essa ferramenta por ai esses dias, só copiar e colar. 😉