Aprenda Markdown: a ferramenta de escrita para desenvolvedores de software

Se você é um engenheiro de software, provavelmente gastou muito tempo refinando seu ambiente para aumentar sua produtividade. Você tem seu IDE favorito. Você tem seu depurador favorito. Você tem sua ferramenta de monitoramento de desempenho favorita. Mas e sua ferramenta para escrever documentação, manuais e relatórios? Afinal, escrever toma uma quantidade não trivial do seu tempo, não é? Na verdade, é hora de levar a sério sua ferramenta de escrita.

E vamos lembrar que você é técnico , então os editores WYSIWYG podem ou não ser a melhor opção para você. Você não quer necessariamente (ou mesmo gosta!) navegar em menus, barras de ferramentas e faixas para formatar seu texto.

E se, em vez disso, você pudesse adicionar facilmente todos os seus estilos de formatação diretamente no texto como uma sintaxe simples embutida para produzir texto totalmente formatado?

Bem, na verdade, você pode. Isso é Markdown e é disso que trata este tutorial.

Quando mais é menos...

O software de processamento de texto é escrito para satisfazer uma gama extremamente ampla de usuários e casos de uso e, como tal, precisa fornecer todos os tipos de funcionalidade. Mas, claramente, apenas um pequeno subconjunto dessa funcionalidade provavelmente será relevante para cada usuário individual. E para a maioria dos usuários, que simplesmente desejam criar um documento (e não precisam criar um folheto ou pôster de marketing), um subconjunto muito pequeno das muitas opções disponíveis é relevante.

Na verdade, a Microsoft percebeu isso claramente há alguns anos, quando redesenhou a interface do usuário do Microsoft Word em grupos funcionais distintos que chamaram de “fitas”. No entanto, curiosamente, a maioria dos usuários dirá que acharam a nova interface mais confusa e difícil de navegar do que seu antecessor.

De fato, mais às vezes pode ser menos quando se trata de facilidade de uso e produtividade.

… e quando menos é mais

Encare, você é um engenheiro de software, não um designer gráfico. Você só quer escrever esse manual, ou documento técnico, ou relatório, e pronto. Você ficará muito feliz e satisfeito com alguns recursos básicos de formatação, como títulos, listas com marcadores ou numeradas e blocos de código. E, sim, alguma formatação de fonte (negrito, itálico, etc.) também seria útil. É sobre isso. (E cara, se você pudesse fazer isso no vi, isso seria realmente incrível!)

Digite Markdown.

O que é Markdown?

John Gruber (com contribuições substanciais do guru técnico e ativista da Internet Aaron Swartz) criou a linguagem Markdown em 2004 com o objetivo de permitir que as pessoas “escrevessem usando um formato de texto simples fácil de ler e escrever e, opcionalmente, convertê-lo para XHTML (ou HTML) estruturalmente válido”.

O Markdown foi projetado para ser legível como está, sem parecer que foi marcado com tags ou instruções de formatação (ao contrário do texto formatado com uma linguagem de marcação como RTF ou HTML que pode ser difícil de criar e difícil de ler em seu formato bruto ).

O Markdown permite que você escreva usando um formato de texto simples fácil de ler e escrever, que pode ser convertido em HTML estruturalmente válido. Então, para ser totalmente preciso, Markdown é realmente duas coisas:

1. Uma sintaxe de formatação de texto simples
2. Uma ferramenta de software (cuja primeira versão foi escrita em Perl) que converte a formatação de texto simples em HTML.

O Markdown incorpora um punhado de convenções de sintaxe simples, bastante intuitivas e fáceis de usar. Especialmente para você como engenheiro de software – que não se incomoda com a necessidade de aprender e usar essas convenções básicas de sintaxe – Markdown pode de fato ser o caminho de menor resistência entre o que você quer escrever e escrever.

Aprenda Markdown: Introdução

Markdown é fácil de aprender. Super fácil. Você pode aprender o básico em cinco minutos e rapidamente se tornará uma segunda natureza. E – assim como a relação entre CSS e pré-processadores CSS – você pode usar o quanto quiser.

Se você está acostumado a qualquer tipo de convenção de escrita de texto simples, então você já deve estar familiarizado com algumas convenções de markdown, como números ou traços no início de uma frase para criar uma lista, asteriscos em torno de uma palavra para ênfase e assim em. Então, por exemplo, se você quiser exibir algo em itálico, simplesmente envolva-o em asteriscos como *this* (em oposição à sintaxe HTML mais desajeitada como <span>this</span> ).

Da mesma forma, você pode especificar um cabeçalho H1 simplesmente adicionando um prefixo '#' à sua linha (por exemplo, # Section Heading , em vez de <h1>Section Heading</h1> ).

Outro grande uso para aprender Markdown, especialmente para nós engenheiros de software, é usá-lo para documentação em repositórios de código-fonte. A maioria dos repositórios inclui um arquivo README.md ( .md é a extensão padrão para um arquivo Markdown). O Github, por exemplo, tem seu próprio “Markdown com sabor do Github”, que adiciona funcionalidades adicionais especificamente para documentação de desenvolvimento. Isso certamente pode economizar tempo ao escrever esta documentação em HTML.

Como um exemplo simples, digamos que você queira incluir o seguinte snippet em sua documentação:

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>Iniciando plugins</h2>

Inicie pluginName em seu contêiner usando jQuery da seguinte forma:

$(function() { $('#container').pluginName(); }); Usando o ID do nosso container, podemos iniciar pluginName com o método jQuery .pluginName() .

Aqui está uma comparação de como isso seria feito em HTML vs. Markdown:

Para obter mais ajuda para começar, há muitos tutoriais de Markdown on-line para ajudá-lo a se atualizar, incluindo uma visão geral do Markdown de John Gruber (criador do Markdown), bem como um tutorial de Markdown on-line.

Analisadores e Ferramentas de Markdown

Depois de escrever seu artigo no Markdown, você precisará de um aplicativo para analisar a sintaxe em HTML. Existem alguns ótimos que são gratuitos , incluindo:

• StackEdit - editor Markdown baseado em navegador que possui algumas opções de sincronização com serviços populares como Google Drive e Dropbox
• Online Kramdown Editor - outro editor Markdown baseado em navegador com uma interface extremamente simples
• Mou - o melhor escritor de Markdown baseado em Mac que encontrei como uma opção mais nerd para desenvolvedores; toneladas de recursos e gratuitos (enquanto em beta) [isso é o que eu usei para escrever este artigo]
• MarkdownPad - ótimo editor Markdown para Windows
• Textos - um bom editor multiplataforma (Mac e Windows); exporta para vários formatos, como PDF, .doc e ePub

Algumas grandes plataformas já adotaram (ou pelo menos permitiram) o uso do Markdown em seus editores para quem deseja usá-lo. Com outros, como WordPress, Evernote e Google Docs, o suporte nativo (no momento em que escrevi este artigo) ainda não foi incorporado, mas soluções personalizadas foram introduzidas por terceiros. Esses incluem:

• A nova e popular plataforma de blogs Ghost, em busca de simplificar a escrita online, usa Markdown para seu editor de conteúdo.
• Para o WordPress, o plug-in Jetpack agora oferece suporte oficial ao Markdown, que você pode ativar em Configurações > Discussão se usar o plug-in. Ou você pode usar um plug-in como o WP-Markdown, que converterá seu conteúdo de remarcação de postagem em HTML e de volta ao Markdown quando precisar editá-lo.
• Para o Evernote, alguns aplicativos Markdown, como o editor online Markable ou o editor do Mac Byword, permitem exportar e publicar diretamente nas notas. Ou se preferir usar o aplicativo da web Evernote diretamente, você pode usar uma extensão do navegador chamada Markdown Here, que converte uma nota selecionada escrita em Markdown em texto formatado com um clique no botão da barra de ferramentas.
• O Google Docs ainda não oferece suporte nativo ao Markdown, mas alguns editores (como o StackEdit) exportarão/sincronizarão diretamente com o Drive.

As desvantagens

Claro, com grande simplicidade vem limitações. Como já expliquei, o Markdown não foi escrito para tarefas complexas de processamento de texto que exigem recursos avançados de formatação. Se é isso que você precisa, o Markdown não é a ferramenta certa.

Mas para desenvolvedores que precisam escrever um manual do usuário ou documentação técnica ou um relatório técnico, o Markdown oferece um equilíbrio quase perfeito entre simplicidade e os recursos de que você precisa.

Talvez a maior desvantagem - especialmente para nós engenheiros que somos viciados em controle de alterações - seja a incapacidade de trabalhar colaborativamente no Markdown e rastrear alterações (uma exceção notável a isso, no entanto, é o plug-in StackEdit para Google Docs). E, claro, com um mínimo de esforço, pode-se simplesmente colaborar em um documento do Markdown por meio de um repositório git e, assim, obter todo o rastreamento de alterações e colaboração de que normalmente se precisa.

Conclusão

Então, aprender Markdown é para todos? Claro que não. Nenhuma ferramenta nunca é.

Mas se você é um engenheiro de software, pode muito bem ser exatamente a ferramenta de escrita que você está procurando. Então, se você ainda não experimentou, você realmente deveria experimentá-lo.