---

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

Introducción

<!--@en Screens are becoming more ubiquous and diverse. Tablets, cell phones, laptop and desktop computers and books are devices where we express and aproach to ideas, causes and stories. This setups a media landscape where we are reading and writing for/from several devices and form factors. In such landscape, popular software, like the Office Suites, can be too resource intensive and overcomplex, becoming ill suited for collaborative and/or multidevice writing, and this creates an increasing tendency for exploring other ways of writing, that recover the focus on the core of the writing experience: putting words together, while providing a simple format and minimalist user experiece that still reflects document structure and presentation. That's why we talk here about **agile and structured documentation**: these techniques are non resource intensive (cognitive or technical), but provide the elements required for writing structured documents layered (if necessary) with sections, subsections, chapters, subchaters and so on and also for supporting other structures like musical or mathematics notations, among others. Big works has been written in such minimalist way, from the complete Wikipedia, to simple manuals and blog posts, like the ones you are reading here. Here we are going to explore one of those light writing way and the tools for it. -->

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 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 escriibr 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á exloraremos uno de esas maneras ligeras de escritura, así como las herramientas para ella.

<!-- Here I'm using alerts in CommonMark see more at: https://docutopia.tupale.co/features?view#Alert-Area --> <!--@en :::success :point_right: **Use Markdown if**: - You want to do colective writing while keeping collaboration and writing simple: - in a sprint o marathon like writing meeting. - in a distributed team of collaborators spread across several timezones and locations. - You want to write from/for several screens and form-factors, while keeping a single source file to produce multiple outputs: printing (PDF), Web (HTML) and mobile (EPUB). ::: -->

:::success :point_right: Usa Markdown si:

• 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). :::

<!-- The Markdown markup language is a tool that allows the authors write from several devices, producing, in a simple way, a single document that can be exported to different formats, media devices and screens: Print (PDF), mobile (EPUB), and Web (HTML). And, despite of the easiness of Markdown, this is not an impediment to create complex documents, like complete books. But you can learn it in an organic fashion, going from the basics, to more complex setups and use cases. This set of features make Markdown also ideal for collaborative organic like documentation excercises and context, like workshops and writing sprints or with a team of collaborators spread across different timezones and places, because tracking changes and making comments can become really easy when a simple format is the base for writing (that is the key of huge successful collective works like Wikipedia, for example). -->

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 de documentación orgánica y colaborativa, como talleres, maratones de escritura o el trabajo con colaboradores repartidos a través de distintas zonas horarioas 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 inmensos obras colaborativos, como la Wikipedia, por ejemplo, pero también puede ser usado en manuales, libros, entre otros, como acá veremos).

<!-- For example, to create the collaborative memory of the workshops and hackathons in our [local hackerspace][hackbo], usually we just create a collaborative plain text editor, called [Etherpad](http://etherpad.org/) and start right there, which makes it more easier for final editions and improvements, without loosing the agility of the process. In fact much of the documentation you are seeing in this Kit was drafted and wrote using such simple tools combination: Markdown + Etherpads (and now we are refining the agile process by using CodiMD). -->

Por ejemplo, para crear una memoria colaborativa de los talleres y hackatones en nuestro hackerspace local, usualmente creamos un texto colaborativo en un editor llamado CodiMD y empezamos a escribir justo ahí, lo cual facilitar 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 tan sencillo formato y herramientas.

<!--@en Markdown is maybe the most popular ligh markup language for documentation used by hundred of thousand of individuals in different communities, like those congregrated in StackOverflow or GitHub and GitLab. -->

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.

<!--@en :::warning :heavy_exclamation_mark: There are several variants of Markdown sharing the basics, while being extended for particular needs and communities. So, when you are learning Markdown, once you have covered the core, you will learn a particular variant of it (or several). ::: -->

:::warning :heavy_exclamation_mark: Existen numerosas variantes de Markdown que comparte lo básico, pero son extendidas para las necesidades de comunidades particulares. Así, cuando estás aprendiendo Markdown, una vez hallas cubierto lo esencial, aprenderás alguna variante particular (o muchas). :::

<!--@en This part of the Kit will provide you with links about how to use such tool and the resources you will find to go futher with that path. Because there is a lot of online resources about it, more that repeating them here, we are going to provide you with a guided tour on how these resources are organized to go from simple to complex. -->

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á organizados para ir de lo simple a clo complejo.

<!-- ## Related tools and examples -->

Herramientas y ejemplos relacionados

<!--@es This section shows some extensions and variants of Markdown, examples of particular works and also tools that can be used for writing on it. -->

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.

<!--@en - (10:44) See [Academic Writing in Markdown](https://youtu.be/hpAJMSS8pvs) to get an overview of the reasons a process behind using this Markup language (most of them still apply outside an academic context). - [Critic Markdown](http://criticmarkup.com/ ): An Markdown variant for collaborative work between authors and editors, which supports highlighting of insertions, deletions, substitutions and comments. - [Pandoc](https://pandoc.org ): A tool that allows importing and exporting from/to several documentation Markup languages, including several variants of Markdown. It has its own extended Markdown syntax to deal with several requirements of book publishing and can combine other more complex Markups (like LaTeX) to create sofisticated publications like books, thesis, among others. - [Data Journalism Handbook, the open sourced Spanish Version][mapeda]: Shows how Pandoc's Markdown can be used to recreate a complete book in PDF format. - [Zettler][zettlr]: A Markdown editor wich supports live preview. - [CodiMD][codimd]: An online collaborative Markdown Editor with syntax highglighting, live preview, document granular permission and support several markdown extensions like Yaml metadata blocks, smileys, alert blocks, source code snippets, among others. - [Markor](https://github.com/gsantner/markor ): Markdown based, Notes, ToDo & Bookmarks Text Editor for Android. -->

• (10:44) Mira Academic Writing in Markdown para obtener una panorámica de las razones y procesos detrás de usar este lenguaje de marcado (la mayoría de ellos aún aplica fuera del contexto académico).
• Critic Markdown: Una variante de Markdown para trabajo colaborativo entre autores y editores, que soporta resaltado de insersiones, borrados, substituciones y comentarios.
• Pandoc: Una herramienta que permite y importar y exportar desde/hacia varios lenguajes de etiquetado, incluyendo diveras variantes de Markdown. It has its own extended Markdown syntax to deal with several requirements of book 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.
• Libro de periodismo de datos, la versión de código abierto: Muestra 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.
• Zettler: Un editor de Markdown que soporta previsualización en caliente.
• 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: Un editor de texto para Android basado en Markdown para notas, agenda y enlaces.

<!--@en ## Learning Markdown Basics -->

Aprendiendo los fundamentos

<!--@en This steps will allow you to learn the basics of Markdown in a progressive fashion. There are plenty of resources to learn it online, so we are not going to repeat them here. Only we are going to introduce some minor modifications to improve the learning experience. Some of the experiences will be related with reading, while others will requiere doing. (Remember to take into account the [conventions](./)). -->

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 requeirán hacer. Recuerda tener en cuenta las conveciones.

<!-- - Get familiar with the syntax starting with the [Markdown Tutorial](https://www.markdowntutorial.com/ ). - Read the Progamming Historian's [Getting Started with Markdown](https://programminghistorian.org/en/lessons/getting-started-with-markdown ) for a more comprenhensive introduction. - Prepare the software for working with Markdown: - For edition: - Create a CodiMD account to work from your web browser from the [Heroku demo server][codimd], or our [own community server][codimd-tupale]. - Install [Atom][atom], to work offline from your own laptop/desktop computer. - For format conversion [install Pandoc][pandoc-install]. - Follow the Progamming Historian's [Sustainable Authorship in Plain Text using Pandoc and Markdown][sustainable-authorship-markdown] for creating your first document, but use CodiMD or Atom instead of the text editor suggested there. -->

• Get familiar with the syntax starting with the Markdown Tutorial.
• Read the Progamming Historian's Getting Started with Markdown for a more comprenhensive introduction.
• Prepare the software for working with Markdown:
  • For edition:
    • Create a CodiMD account to work from your web browser from the Heroku demo server, or our own community server.
    • Install [Atom][atom], to work offline from your own laptop/desktop computer.
  • For format conversion install Pandoc.
• Follow the Progamming Historian's Sustainable Authorship in Plain Text using Pandoc and Markdown for creating your first document, but use CodiMD or Atom instead of the text editor suggested there.