---
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
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.
<!-- Here I'm using alerts in CommonMark see more at:
https://docutopia.tupale.co/features?view#Alert-Area
-->
:::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).
:::
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).
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).
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.
:::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).
:::
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.
## Related tools and examples
This section shows some extensions and variants of Markdown, examples of particular
works and also tools that can be used for writing on it.
- <i class="fa fa-play-circle fa-fw"></i>(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.
- [Atom][atom]: A text editor wich supports Markdown live preview, available.
- [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.
## Learning Markdown Basics
This steps will allow you to learn the basics of Markdown in a progressive fashion.
There are plenty of resources to learn Markdown 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](./)).
- <i class="fa fa-wrench fa-fw"></i> Get familiar with the syntax starting with the
[Markdown Tutorial](https://www.markdowntutorial.com/ ).
- <i class="fa fa-eye fa-fw"></i> Read the Progamming Historian's [Getting Started with Markdown](https://programminghistorian.org/en/lessons/getting-started-with-markdown )
for a more comprenhensive introduction.
- <i class="fa fa-wrench fa-fw"></i> 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].
- <i class="fa fa-wrench fa-fw"></i> 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.
[atom]: https://atom.io
[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]: https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown