Markdown

Si te consideras desarrollador, deberías saber Markdown

La mayoría de desarrolladores tenemos una relación extraña con el proceso de documentación.

El desarrollo de Software es una actividad creativa, con unas reglas claras y a menudo excitante. Documentar, sin embargo, es aburrido y además no hay un consenso claro de cómo debe llevarse a cabo. Cada compañía, cada desarrollador o incluso cada proyecto tienen su propia manera de abordar el tema de la documentación.

Hay muchas técnicas y, desde luego cada tipo de proyecto tiene sus propios requerimientos de documentación. No es lo mismo documentar una librería que va a ser usada por otros desarrolladores que documentar el uso de un complejo sistema de gestión. Para algunos proyectos será mejor escribir un completo manual de usuario, para otros una wiki, o un Javadoc, un conjunto de páginas html, un simple README en texto plano, etc.

En lo personal, a mí me suele gustar que un sistema sea intuitivo y autoexplicativo y que requiera el mínimo posible de documentación y, en lo posible, que la construcción de esa documentación esté estrechamente ligada al desarrollo del propio proyecto. Idealmente, que se aloje en el mismo repositorio y que vaya evolucionando a la vez que el propio desarrollo, evitando que se quede obsoleta.

Como Geek que soy, me gustan los archivos en texto plano incluídos, como digo, en el mismo repositorio que el código. El texto plano es ligero, es estándar y no requiere de editores específicos. Por contra, es duro de leer, árido e incluso un poco feo, sobre todo cuando hablamos de documentos de tamaño considerable.

Una buena alternativa son los archivos HTML. También son ligeros y son un estándar y además, permiten dar formato a nuestros ducumentos, así como incluir imágenes y enlazarlos entre ellos. Con HTML podemos, sin duda, dotar a nuestros documentos de un atractivo mucho mayor.

Prácticamente cualquier desarrollador tiene los conocimientos suficientes de HTML como para crear documentos básicos. Lo que pasa es que crear archivos HTML con editores de texto es un poco engorroso. Además, aunque a nivel básico, HTML es sencillo, se puede complicar bastante si queremos dotarlo de un estilado complejo.

Podemos, por supuesto, usar editores WYSIWYG pero, en este caso, perdemos control sobre el documento que estamos generando.

Ante esto, Markdown es una gran alternativa. Markdown es un lenguaje de marcado muy ligero, basado en texto, que permite dar una estructura a nuestros documentos de una forma muy sencilla e intuitiva. Además, nos permite incluir imágenes y enlaces. A continuación, un ejemplo de código escrito en Markdown:

# Esto es una cabecera de nivel 1
## Esto es una cabecera de nivel 2
*Este texto está en cursiva*
**Y este otro está en negrita**
- Primer elemento de una lista
- Segundo elemento de la misma lista
[Esto es un enlace al mejor Blog del mundo](https://www.arturo-jimenez.es)
```Y esto es un bloque de código```

Con un visor de markdown el código de arriba se visualizaría así:

Esto es una cabecera de nivel 1

Esto es una cabecera de nivel 2

Este texto está en cursiva
Y este otro está en negrita

  • Primer elemento de una lista
  • Segundo elemento de la misma lista

Esto es un enlace al mejor Blog del mundo

Y esto es un bloque de código

Y con esto quiero justificar el título del Post: Si te consideras desarrollador, deberías saber Markdown. Pero si aún no lo sabes, no te preocupes demasiado porque es realmente sencillo.

Comparte

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *