Learn Markdown: la herramienta de escritura para desarrolladores de software

Si es ingeniero de software, probablemente haya pasado mucho tiempo refinando su entorno para aumentar su productividad. Tienes tu IDE favorito. Tienes tu depurador favorito. Tienes tu herramienta de monitoreo de rendimiento favorita. Pero, ¿qué pasa con su herramienta para escribir documentación, manuales e informes? Después de todo, escribir requiere una cantidad no trivial de tu tiempo, ¿no es así? De hecho, es hora de tomarse en serio su herramienta de escritura.

Y recordemos que eres técnico , por lo que los editores WYSIWYG pueden o no ser la mejor opción para ti. No necesariamente quiere (¡ni siquiera le gusta!) Navegar por los menús, las barras de herramientas y las cintas para dar formato a su texto.

Entonces, ¿qué sucede si, en cambio, puede agregar fácilmente todos sus estilos de formato directamente en el texto como una sintaxis en línea simple para producir un texto con formato completo?

Bueno, de hecho, puedes. Eso es Markdown y de eso se trata este tutorial.

Cuando más es menos…

El software de procesamiento de textos está escrito para satisfacer una gama extremadamente amplia de usuarios y casos de uso y, como tal, debe proporcionar todo tipo de funcionalidad. Pero claramente, es probable que solo un pequeño subconjunto de esa funcionalidad sea relevante para cada usuario individual. Y para la mayoría de los usuarios, que simplemente desean crear un documento (y no necesitan diseñar un folleto o póster de marketing), un subconjunto muy pequeño de las muchas, muchas opciones disponibles es relevante.

De hecho, Microsoft claramente se dio cuenta de esto hace unos años cuando rediseñaron la interfaz de usuario de Microsoft Word en distintos grupos funcionales que llamaron "cintas". Sin embargo, curiosamente, la mayoría de los usuarios le dirán que encontraron la nueva interfaz más confusa y difícil de navegar que su predecesora.

De hecho, a veces más puede ser menos cuando se trata de facilidad de uso y productividad.

… y cuando menos es más

Acéptalo, eres un ingeniero de software, no un diseñador gráfico. Solo quiere escribir ese manual, o documento técnico, o informe, y listo. Estará muy feliz y contento con algunas capacidades básicas de formato como encabezados, listas numeradas o con viñetas y bloques de código. Y, oh sí, algún formato de fuente (negrita, cursiva, etc.) también sería útil. Eso es todo. (Y hombre, si pudieras hacerlo en vi, ¡sería realmente increíble!)

Introduzca Markdown.

¿Qué es Markdown?

John Gruber (con contribuciones sustanciales del gurú técnico y activista de Internet Aaron Swartz) creó el lenguaje Markdown en 2004 con el objetivo de permitir a las personas "escribir utilizando un formato de texto sin formato fácil de leer y escribir y, opcionalmente, convertirlo a XHTML estructuralmente válido (o HTML)”.

Markdown se diseñó para que se pueda leer tal cual, sin que parezca que se ha marcado con etiquetas o instrucciones de formato (a diferencia del texto formateado con un lenguaje de marcado como RTF o HTML, que puede ser difícil de crear y difícil de leer en su formato original). ).

Markdown le permite escribir utilizando un formato de texto sin formato fácil de leer y escribir, que luego se puede convertir en HTML estructuralmente válido. Entonces, para ser completamente precisos, Markdown es realmente dos cosas:

1. Una sintaxis de formato de texto sin formato
2. Una herramienta de software (cuya primera versión se escribió en Perl) que convierte el formato de texto sin formato en HTML.

Markdown incorpora un puñado de convenciones de sintaxis simples, bastante intuitivas y fáciles de usar. Especialmente para usted como ingeniero de software, que no se desanima por la necesidad de aprender y usar estas convenciones de sintaxis básicas, Markdown puede ser el camino de menor resistencia entre lo que quiere escribir y escribirlo.

Aprender Markdown: Primeros pasos

Markdown es fácil de aprender. Muy facil. Puede aprender los conceptos básicos en cinco minutos y rápidamente se convertirá en una segunda naturaleza. Y, al igual que la relación entre CSS y los preprocesadores de CSS, puede usar tanto como desee.

Si está acostumbrado a cualquier tipo de convenciones de escritura de texto sin formato, es posible que ya esté familiarizado con algunas convenciones de rebajas, como números o guiones al comienzo de una oración para crear una lista, asteriscos alrededor de una palabra para enfatizar, etc. en. Entonces, por ejemplo, si desea mostrar algo en cursiva, simplemente envuélvalo en asteriscos como *this* (a diferencia de la sintaxis HTML más tosca como <span>this</span> ).

De manera similar, puede especificar un encabezado H1 simplemente agregando un prefijo '#' a su línea (por ejemplo, # Section Heading , en lugar de <h1>Section Heading</h1> ).

Otro gran uso para aprender Markdown, especialmente para nosotros, los ingenieros de software, es usarlo para la documentación de los repositorios de código fuente. La mayoría de los repositorios incluyen un archivo README.md ( .md es la extensión estándar para un archivo Markdown). Github, por ejemplo, tiene su propio "Marcado con sabor a Github", que agrega funcionalidad adicional específicamente para la documentación de desarrollo. Esto sin duda puede ahorrar tiempo en lugar de tener que escribir esta documentación en HTML.

Como ejemplo simple, supongamos que desea incluir el siguiente fragmento en su documentación:

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

Inicie pluginName en su contenedor usando jQuery de la siguiente manera:

$(function() { $('#container').pluginName(); }); Usando la ID de nuestro contenedor, podemos iniciar pluginName con el método jQuery .pluginName() .

Aquí hay una comparación de cómo se haría esto en HTML frente a Markdown:

Para obtener más ayuda para comenzar, hay muchos tutoriales de Markdown en línea que lo ayudarán a ponerse al día, incluida una descripción general de Markdown de John Gruber (el creador de Markdown), así como un tutorial en línea de Markdown.

Analizadores y herramientas de Markdown

Una vez que haya escrito su artículo en Markdown, necesitará una aplicación para analizar la sintaxis en HTML. Hay algunos excelentes que son gratuitos , incluidos:

• StackEdit: editor de Markdown basado en navegador que tiene algunas opciones de sincronización con servicios populares como Google Drive y Dropbox
• Online Kramdown Editor: otro editor de Markdown basado en navegador con una interfaz extremadamente simple
• Mou: el mejor escritor de Markdown basado en Mac que he encontrado como una opción más geek para desarrolladores; toneladas de funciones y gratis (mientras está en versión beta) [esto es lo que solía escribir este artículo]
• MarkdownPad - gran editor de Markdown para Windows
• Textos: un buen editor multiplataforma (Mac y Windows); exporta a múltiples formatos como PDF, .doc y ePub

Algunas plataformas importantes ya han adoptado (o al menos permitido) el uso de Markdown en sus editores para aquellos que deseen usarlo. Con otros, como WordPress, Evernote y Google Docs, el soporte nativo (en el momento de escribir este artículo) aún no está integrado, pero terceros han introducido soluciones personalizadas. Éstos incluyen:

• La nueva y popular plataforma de blogs Ghost, en busca de simplificar la escritura en línea, utiliza Markdown para su editor de contenido.
• Para WordPress, el complemento Jetpack ahora admite oficialmente Markdown, que puede habilitar en Configuración> Discusión si usa el complemento. O puede usar un complemento como WP-Markdown que convertirá el contenido de su publicación en HTML y volverá a Markdown cuando necesite editarlo.
• Para Evernote, algunas aplicaciones de Markdown, como el editor en línea Markable o el editor de Mac Byword, permiten exportar y publicar directamente en las notas. O si prefiere usar la aplicación web de Evernote directamente, puede usar una extensión de navegador llamada Markdown Here que convierte una nota seleccionada escrita en Markdown en texto formateado con un clic en el botón de la barra de herramientas.
• Google Docs aún no es compatible de forma nativa con Markdown, pero algunos editores (como StackEdit) exportarán/sincronizarán directamente con Drive.

las desventajas

Por supuesto, con gran simplicidad vienen las limitaciones. Como ya expliqué, Markdown no fue escrito para tareas complejas de procesamiento de textos que requieren funciones de formato avanzadas. Si eso es lo que necesita, Markdown no es la herramienta adecuada.

Pero para los desarrolladores que necesitan escribir un manual de usuario, documentación técnica o un informe técnico, Markdown ofrece un equilibrio casi perfecto entre la simplicidad y las funciones que necesita.

Quizás el mayor inconveniente, especialmente para nosotros, los ingenieros que somos adictos al control de cambios, es la incapacidad de trabajar en colaboración en Markdown y realizar un seguimiento de los cambios (sin embargo, una excepción notable a esto es el complemento StackEdit para Google Docs). Y, por supuesto, con una cantidad mínima de esfuerzo, uno puede simplemente colaborar en un documento de Markdown a través de un repositorio git y, por lo tanto, obtener todo el seguimiento de cambios y la colaboración que normalmente necesita.

Conclusión

Entonces, ¿aprender Markdown es para todos? Por supuesto que no. Ninguna herramienta lo es.

Pero si eres ingeniero de software, podría ser precisamente la herramienta de escritura que estabas buscando. Entonces, si aún no lo has probado, realmente deberías probarlo.