A lo largo de los últimos años para la redacción de documentación he utilizado infinidad de sistemas. Entiéndase sistema de documentación por algún software que a partir de un fichero de texto convenientemente redactado genere una salida que sea ya publicable bien en Internet (como documento HTML en general), bien para imprimir (por ejemplo en PDF).

En función de las necesidades (a veces impuestas por otros, otras por iniciativa propia) he ido abordando los diferentes sistemas. Ciertamente todos tienen puntos en común aunque hay dos grupos principales: los de semántica fuerte y los de semántica débil.

Por otro lado, la proliferación del mantenimiento diferentes repositorios de documentación en gestores de contenidos como Plone o wikis como Confluence o MediaWiki provoca que acabemos utilizando como 3 o 4 sistemas de marcado. En cualquier caso estas soluciones son claramente superiores frente a las ya anticuadas carpetas de archivos en Word o Writer, y esto el que haya tenido que escribir un documento de forma colaborativa lo comprenderá perfectamente. La verdad es que tras unos minutos te haces a cualquiera de ellos y permite concentrarse bastante bien en lo importante la documentación.

Sistemas de semántica fuerte

Estos lenguajes marcan claramente los diferentes tipos de contenidos con algún tipo de comando. Por ejemplo, con LaTeX es más que conveniente crear comandos para palabras extranjeras o comandos de una terminal (en DocBook viene de serie).

Son sistemas complejos, difíciles de aprender en general pero a la vez bastante potentes. Personalmente he utilizado mucho LaTeX y algo DocBook, aunque ciertamente cada vez menos en favor de los semánticamente más ligeros.

Ambos son excelentes sistemas con sus puntos fuertes y sus puntos débiles. Por ejemplo: LaTeX no tiene rival en la elaboración de documentación científica con fórmulas y exigentes necesidades de maquetación mientras que DocBook es un sistema orientado perfectamente para la publicación de documentación técnica (especialmente en el área de la ingeniería del software).

Producir documentación en estos sistemas requiere de bastante tiempo, más que los que a continuación comentaré, pero en determinados ambientes son una apuesta a medio plazo bastante conveniente, existen decenas de proyectos de software que mantienen su documentación en DocBook como por ejemplo PostgreSQL o GeoNetwork OpenSource.

Sistemas de semántica débil

Estos sistemas tienen poca a ninguna semántica en sus comandos, fuera de las mínimas necesarias para producir tablas, crear enlaces, negritas, cursivas y demás. En este área ahora mismo manejo, y espero no olvidarme de ninguno:

• Plone, reStructured Text
• Wiki de OSGeo, mediawiki
• Wiki del trabajo, Confluence
• Trac’s varios que de vez en cuando edito, el suyo
• Edición de este blog, txt2tags (fuera, los contenidos se suben como xhtml) y antes directamente en textile

De estos, el más evolucionado es sin duda reStructured Text, con algunas marcas para escribir notas, comandos para que se genere de forma automatizada la tabla de contenidos y cosas así. Por otro lado, hacer tablas en reStructured Text es prácticamente ASCII-art y un auténtico fastidio.

La ventaja de estos sistemas es que en general los ficheros o textos que se escriben son altamente legibles (al contrario de DocBook por ejemplo) y se pueden redactar con cualquier editor de textos, del viejo Vim a cosas más modernas como JEdit.

Por ejemplo, para redactar este artículo estoy utilizando un marcado débil muy sencillito llamado txt2tags que funciona con Python. Si estás en Windows, creo que puedes bajarte una versión que es un ejecutable que lleva ya un pequeño Python dentro, si estás en Linux y MacOS seguro que tienes Python instalado y no tienes más que dejar caer el script en algún sitio de tu PATH del sistema.

Por último, para escribir, como editor de texto (independientemente de que escriba en txt2tags o reStructured Text) utilizo este ordenador PyRoom, un clon libre del maquero WhiteRoom (en Windows tienes el bonito y barato Q10). Todos ellos te dejan una buena pantalla donde no hay ni botones ni menús, ¡¡sólo un cursor parpadeante que espera que escribas cosas interesantes!!