Documentar, adiós Word/Writer hola Firefox


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:

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!!

About these ads

5 pensamientos en “Documentar, adiós Word/Writer hola Firefox

  1. Anónimo

    Excelente post!Haz logrado concretar un montón de ideas sueltas que tenía en la cabeza!!!

    Mi CV está escrito en txt2tags, mis presentaciones las hago sobre MoinMoin y para documentar software utilizo reStructuredText (y Sphinx!)

    F. Palm

  2. xurxo

    Gracias Francisco,

     De las presentaciones ya hablaré en otro
    momento, que ahí también me da por hacer cosas raras de vez en
    cuando… ¡de powerpoint 2007 al freemind hay mucho trecho!

    --
    XuRxO
    
  3. vehrka

    La verdad es que últimamente estoy dándole mucha caña a Google Docs, no
    necesariamente para cosas del curro, ni cartográficas, pero en
    combinación con Google Gears para trabajar en modo offline se convierte
    en un poderoso aliado en viajes… y ¡¡simplemente tirando de Firefox!!


    Pedro-Juan Ferrer Matoses (vehrka)

  4. xurxo

    mmm no sabía que ya estaba activo el servicio offline de google docs, habrá que probarlo, aunque en un minipc creo que pyroom con txt2tags sigue siendo MUY competitivo (para mí que soy un friki asqueroso, ya lo sé)

    --
    XuRxO
    
  5. vehrka

    Puedes activar el modo offline si tienes instalado el plugin de Google Gears para Firefox (supongo que con Chrome va nativo) y TIENES LA INTERFAZ EN INGLES… ya sabéis las novedades siempre primero en la lengua de Chaquespire


    Pedro-Juan Ferrer Matoses (vehrka)

Los comentarios están cerrados.