---
breaks: false
repo: https://mutabit.com/repos.fossil/documentaton/
translations:
- en: https://docutopia.tupale.co/inkit:r3p:agiledoc#
- es: https://docutopia.tupale.co/documentaton:agiledoc.es#
sync:
- translations://es
- repo://es/capitulos/doc-agil.md
Pending: Traducir el documento de inglés a español.
---
# Markdown: Documentación ágil y estructurada
{width=70%}
## Introducción
Las pantallas se están volviendo más ubicuas y diversas.
Tabletas, teléfonos celulares, computadores portátiles y de escritorio y los libros son aparatos donde expresamos
y nos aproximamos a ideas, causas e historias.
Esto configura un paisaje de medios donde estamos leyendo y escribiendo desde y para distintos aparatos y
factores de forma.
En tal panorama diverso, software popular, como las _suites_ de oficina, pueden ser consumir demasiados recursos y
ser extra complicadas, haciéndose inadecuadas para escritura colaborativa y/o multi-dispositivo, y esto crea una creciente
tendencia a explorar otras maneras de escribir, que recobran el foco en el núcleo de la experiencia de escritura:
poner palabras juntas, mientras que proveen un formato sencillo y una experiencia de usuario minimalista que aún
refleja la estructura del documento y su presentación.
Es por eso que hablamos acá de **documentación ágil y estructurada**: estas técnicas no son voraces en recursos
(cognitivos o tecnológicos), pero proveen los elementos necesarios para escribir documentos estructurados jerárquicos
(si es necesario), con secciones, subsecciones, capítulos, subcapítulos etc y también soportan otras formas de estructuras,
como notaciones musicales o matemáticas, entre otras.
Acá exploraremos uno de esas maneras ligeras de escritura, así como las herramientas para ella.
:::info
::: {.admonition}
<!-- :point_right: -->
**Usa Markdown si**:
- Quieres crear rápidamente documentos hipertextuales para publicar en la web, manteniendo el código fuente
de los mismos legible y portable a otros formatos.
- Quieres escribir colectivamente mientras mantienes la colaboración y la escritura simple:
- en un encuentro tipo maratón o carrera de escritura.
- en un equipo distribuido de colaboradores distribuidos en varias zonas horarias y ubicaciones.
- Si quieres escribir desde/hacia varias pantallas y factores de forma, mientras quieres mantener un
único archivo fuente para producir múltiples salidas: impresa (PDF), web (HTML) y móvil (EPUB).
:::
:::
El lenguaje de etiquetado Markdown es una herramienta que permite a los autores escribir desde diversos
dispositivos, produciendo, de manera sencilla un documento que puede ser exportado a diversos
formatos, dispositivos de medios y pantallas: impresa (PDF), móvil (EPUB) y web (HTML).
Y, a pesar de la facilidad de Markdown, esto no es un impedimiento para crear complejos documentos, como libros completos.
Pero puedes aprenderlo de una manera orgánica, yendo de las bases a más complejas configuraciones y casos de uso.
Este conjunto de características hacen también de Markdown ideal para ejercicios y contextos de documentación
orgánica y colaborativa, como talleres, maratones de escritura o el trabajo con colaboradores repartidos a través de
distintas zonas horarias y lugares, porque trazar los cambios y hacer comentarios puede convertirse en algo
realmente simple, cuando un formato simples es la base para la escritura (esta es la clave de inmensas obras colaborativas,
como la Wikipedia, por ejemplo, pero también puede ser usado en manuales, libros, entre otros, como acá veremos).
Por ejemplo, para crear una memoria colaborativa de los talleres y hackatones en nuestro [hackerspace local][hackbo],
usualmente creamos un texto colaborativo en un editor llamado [CodiMD](http://demo.codimd.org/) y empezamos a escribir justo ahí, lo cual
facilita hacer ediciones y mejoras a dicha memoria, sin perder la agilidad en el proceso.
De hecho, mucha de la documentación que estás viendo en esta obra, fue bosquejada y escrita usando un formato
y herramientas tan sencillas (en comparación con sus contrapartes de la ofimática clásica).
Markdown es quizás el lenguaje de etiquetado más popular para documentación usado por millones de personas
en diferentes comunidades, como aquellas que se congregan en StackOverflow, GitHub y GitLab.
:::info
:::{.admonition}
Existen numerosas variantes de Markdown que comparten lo básico, pero son extendidas para las necesidades de
comunidades particulares.
Ellas se están unificando en un estándar conocido como [CommonMark](https://commonmark.org/).
Así, cuando estás aprendiendo Markdown, una vez hayas cubierto lo esencial, aprenderás alguna variante particular
(o muchas) que comparten y convergen hacia un estandar.
:::
:::
Esta parte de la obra te proveerá con los enlaces sobre cómo usar dicha Markdown y los recuros que puedes encontrar
para profundizar en este camino.
Debido a que hay muchos recursos en línea sobre éste, más que repetirlos acá, lo que haremos será proveerte con un
tour guiado sobre cómo estos recursos están organizados para ir de lo simple a lo complejo.
## Herramientas y ejemplos relacionados
Esta sección muestra algunas extensiones y variantes de Markdown, ejemplos de obras particulares y también
herramientas que pueden ser usadas para escribir en él.
:::success
::: {.admonition}
<i class="fa fa-wrench fa-fw"></i> Visita los siguientes enlaces para adquirir una visión panorámica de cómo está siendo usando Markdown y por qué.
- [ ] <i class="fa fa-play-circle fa-fw"></i>(10:44) Mira [Academic Writing in Markdown](https://youtu.be/hpAJMSS8pvs)
para obtener una panorámica de las razones y procesos detrás de usar este lenguaje de etiquetado (la
mayoría de ellos aún aplica fuera del contexto académico).
- [ ] [Critic Markdown](http://criticmarkup.com/): Una variante de Markdown para trabajo colaborativo entre autores y editores, que
soporta resaltado de insersiones, borrados, substituciones y comentarios.
- [ ] [Pandoc](https://pandoc.org): Una herramienta que permite y importar y exportar desde/hacia
varios lenguajes de etiquetado, incluyendo diveras variantes de Markdown.
Tiene su propia sintaxis extendida de Markdown para lidiar con varios requerimientos de la publicación
de libros y puede combinar lenguajes de etiquetado más complejos (como LaTeX) para crear sofisticadas
publicaciones, como libros, tesis y revistas, entre otras.
- [ ] Libros: Muestran cómo el Markdown de Pandoc puede ser usado para recrear un libro completo en formato PDF,
incluyendo su diagramación, gráficas y tipografías.
- [ ] [Libro de periodismo de datos, la versión de código abierto][mapeda].
- [ ] [Documentatón: técnicas y herramientas ágiles y resilientes para escribir y publicar juntos][documentaton].
- [ ] [Zettler][zettlr]: Un editor de Markdown que soporta previsualización en vivo.
- [ ] [CodiMD][codimd]: Un editor colaborativo para Markdown con resaltado sintáctico, previsulización en vivo
permisos granulares sobre los documentos y soporte para varias extensiones de Markdown como bloques
de metadatos en Yaml, _smileys_, bloques de alerta y trozos de código, entre otros.
- [ ] [Markor](https://github.com/gsantner/markor ): Un editor de texto para Android basado en Markdown para notas, agenda y enlaces.
:::
:::
## Aprendiendo los fundamentos
Estos pasos te permitirán aprender las bases de Markdown de una manera progresiva.
Hay muchos recursos para aprenderlo en línea, así que no vamos a repetirlos acá.
Sólo vamos a introducir algunas modificaciones mínimas para mejorar la experiencia de aprendizaje.
Algunas de las experiencias estarán relacionadas con leer, mientras otras requerirán hacer..
:::warning
:::{.admonition}
Algunos sitios como el del *Historiador que Programa*, sugerirán infraestructuras gratuitas para que hagas los ejercicios.
Nosotros te proponemos usar las que ha dispuesto nuestra comunidad, pues ya hicimos el recorrido por las primeras
y decidimos disponer y alojar las nuestras para tener mayor autonomía, estabilidad y resiliencia.
Así, cuando un ejercicio del Historiador que Programa te proponga usar Stack Edit, por ejemplo, nosotros te
sugeriremos usar [Docutopia][docutopia].
:::
:::
:::success
:::{.admonition}
- [ ] <i class="fa fa-wrench fa-fw"></i> Familiarizate con la sintaxis, empezando con el
[Tutorial de Markdown](https://www.markdowntutorial.com/ ).
- [ ] <i class="fa fa-eye fa-fw"></i> Lee del _Historiador que Programa_ [Introducción a Markdown](https://programminghistorian.org/es/lecciones/introduccion-a-markdown)
para una introducción más comprenhensiva.
- [ ] <i class="fa fa-wrench fa-fw"></i> Prepara el software para trabajar con Markdown:
- Para su edición:
- [ ] Crea una cuenta de CodiMD para trabajar desde tu navegador web en [Docutopia][codimd-tupale], nuestro propio servidor comunitario para dicha tecnología. (Hay un [servidor de demo][codimd] de CodiMD, provisto por sus creadores, pero los documentos allí son más volátiles que en nuestro propio servidor..
- [ ] Instala [Zettlr][zettlr], para trabajar fuera de línea en tu propio computador portátil o de escritorio.
- Para conversión de formatos [instala Pandoc][pandoc-install].
- <i class="fa fa-wrench fa-fw"></i> Sigue la [Escritura sostenible en texto plano usando Pandoc y Markdown][sustainable-authorship-markdown-es] de el Historiador que Programa, para crear tu primer documento,
pero usa CodiMD or Zettlr en lugar del editor de texto sugerido allí.
:::
:::
[codimd]: https://hackmd-ce.herokuapp.com/
[codimd-tupale]: https://docutopia.tupale.co/
[etherpad]: http://etherpad.org/
[hackbo]: http://hackbo.co/
[mapeda]: http://mutabit.com/repos.fossil/mapeda/
[pandoc-install]: https://pandoc.org/installing.html
[sustainable-authorship-markdown-es]: https://programminghistorian.org/es/lecciones/escritura-sostenible-usando-pandoc-y-markdown
[zettlr]: http://zettlr.com/