You are currently browsing the tag archive for the ‘documentación’ tag.

Por qué utilizar un wiki

Siempre cuando alguien entra como empleado en una nueva empresa, se puede observar un comportamiento que es casi común a todos los novatos. Las primeras semanas nunca se van sin su cuaderno y su bolígrafo cuando van a hablar con alguien. Ahí se apuntan, quién es el responsable para qué proyecto, que es la dirección IP de su equipo y en qué carpeta de red se encuentra qué documento. Tras unos meses, estas ganas de apuntarse todo se van. Ya han aprendido lo más importante y lo nuevo memorizan.

Todos los nuevos empleados apuntan más o menos lo mismo en su cuaderno. Esto no extraña ya que empiezan a trabajar en la misma empresa. La pregunta es, ¿por qué los veteranos no pasan sus cuadernos a los nuevos empleados? Con esto ya tendrían apuntado todo y lo único que necesitan es actualizar alguna información obsoleta.

Pues, esto se puede hacer con un wiki. En un wiki, cada uno puede escribir lo que sabe y puede corregir lo que los demás ya han apuntado. La meta de un wiki es unir el saber de dos medio sabios a un conocimiento completo. El sitio más famoso que funciona con este método es la Wikipedia – de ahí el nombre “wiki”. Pero el mismo software se puede usar también para la empresa.

En lugar de apuntar tus notas en un cuaderno, lo haces en un wiki. Otro empleado nuevo puede entonces utilizar estas notas ya hechas y completarlos con lo que faltaba por apuntar. Un empleado veterano puede corregir información insuficiente. De esta forma surge un sitio de información completa, que está vivo y se actualiza constantemente – al menos si los empleados lo utilizan en lugar de sus cuadernos.

Cómo utilizar un wiki

La pregunta es, qué tipo de información ponemos en un wiki. Para cada proyecto ya suele haber una documentación que no hace falta repetir. Por eso ponemos en el wiki lo que no hemos puesto en ningún lado todavía.

Típicamente escribimos en un wiki lo que llamamos “meta-información”. No guardamos la documentación del proyecto, sino dónde está guardado o quién podría ayudarnos. Es decir, apuntamos lo mismo que el nuevo empleado apuntaría en su cuaderno. Sólo que de esta forma la información está disponible para todos y se puede actualizar y mejorar continuamente.

Usar el wiki puede ser más rápido que un cuaderno. Recibimos un email con los enlaces a los ficheros fuente. Pegamos este email en el wiki y ya tenemos una página con los enlaces importantes. Preguntamos el cliente sobre las especificaciones que faltaban en la especificación y apuntamos las respuestas en el wiki. Así no sólo tenemos toda la información en el mismo sitio, sino surge automáticamente una parte de la documentación del proyecto.

De esta forma el wiki no sólo puede sustituir a los cuadernos sino también a los archivos de email. En lugar de que cada uno tiene su colección de correspondencia, la ponemos a disposición de todos los interesados. Un wiki puede incluso sustituir presentaciones de tipo PowerPoint. Simplemente proyectamos a la pared la página correspondiente en lugar de una presentación. La información presentada ya está en el wiki y si hace falta cambiar algo, se puede corregir directamente durante la presentación. Al final de la presentación, los oyentes puede consultarla en el wiki al salir de la sala de reunión.

Qué tipo de wiki es recomendable

El software más conocido es “Wikimedia”, que es lo que usa la Wikipedia. No obstante, esta aplicación no ofrece tablas de contenido con jerarquía que permitiría ordenar páginas con una estructura lógica. El wiki “Confluence” de la empresa Atlassian tiene esta funcionalidad, pero este es de pago. Hay tantos tipos de wiki distintos que alguien amable ya creó el sitio Wiki Choice Wizard, para elegir el más adecuado para tus necesidades.

Vale la pena dedicarle tiempo a la selección del tipo de wiki, ya que será una herramienta con un uso de larga duración.

Lectura adicional

La primera tarea del sistema de documentación automatizado doxygen es la creación de un manual de referencia del código del programa. Sin embargo, doxygen ofrece también la funcionalidad de añadir un texto libre. Por la capacidad de doxygen de entender etiquetas de HTML, podemos editar un documento HTML con un editor aparte y luego integrarlo en la documentación generada con doxygen. Esto nos trae la ventaja de poder entregar una documentación completa y actualizada con cada ejecución de doxygen.

Creación de documentación libre

Doxygen conoce varias etiquetas para la creación de documentación libre. En primer lugar están las etiquetas \mainpage, \page y \subpage para la creación y la estructuración de páginas independientes. Dentro de cada página podemos estructurar el texto en apartados con las etiquetas provenientes LaTeX: \section, \subsection, \subsubsection y \paragraph. Conviene guardar la documentación libre en un fichero aparte por no tener correspondencia a ninguna entidad de código en concreto. El sufijo previsto para estos ficheros es dox, es decir, podemos crear una carpeta “doc” o “dox” que incluye todos los ficheros fuente que contienen documentación pero ninguna línea de código ejecutable.

Las etiquetas mencionadas arriba deben encontrarse dentro de un comentario de documentación. Lo más conveniente en este caso es abrir el comentario con /** o /*! en la primera línea y cerrarlo con */ en la última. Doxygen no exige iniciar una línea en medio con *. Ver la documentación de doxygen para un ejemplo.

Lo normal sería escribir la documentación libre en un fichero de texto, pero como ya he mencionado, en este artículo queremos averiguar, si podemos utilizar fuentes escritos en HTML. Dentro de lo que cabe tenemos dos estrategias para usarlas:

  1. Crear un documento HTML que doxygen lee y interpreta como un fichero fuente, es decir, un fichero .dox, y
  2. integrar un documento HTML externo

Ambas maneras tienen ventajas y desventajas que detallaremos a continuación.

Procesar HTML como fichero fuente

Podemos crear un fichero HTML y dejarlo procesar por doxygen como si fuera un fichero fuente. Doxygen entiende la mayoría de las etiquetas de HTML. Las que no entiende son en primer lugar etiquetas de contenido dinámico como OBJECT o EMBED. Esto no es de extrañar ya que doxygen no es un navegador de Internet sino una herramienta de documentación. Lo que duele más que tampoco entiende las etiquetas de cabecera. A contrario de lo que diga la documentación, la versión 1.7.1 que yo probé, no reconoce nada de lo que aparece entre <HEAD> y </HEAD> y tampoco la etiqueta BODY. Estas etiquetas aparecen entonces como cualquier texto normal.

Doxygen tampoco reconoce el comentario de HTML <– –>. Por lo tanto no podríamos esconder la apertura del comentario de documentación /** dentro de un comentario para que no nos aparezca si abrimos el fichero HTML en un navegador. En fin, no es posible crear un documento HTML que queda perfecto tanto en un navegador y en el resultado de doxygen a la vez. Todavía necesitamos un poco de trabajo manual:

Creamos un fichero dox que contiene algo como lo siguiente

/** \page mi_pagina_html Mi página en HTML
<h1>Soy un título</h1>
<p>En esta página podemos hablar de asuntos <em>muy</em> importantes.</p>
*/

Entre la primera y la última línea copiamos todo lo que se encuentra entre las etiquetas <BODY> y </BODY> en el documento HTML. (En este caso sólo he puesto dos líneas.)

La ventaja de esta manera es que doxygen crea una salida homogénea con las otras partes de la documentación. Más interesante aún es que doxygen enlaza los nombres de identificadores con la referencia correspondiente. De esta manera podemos, por ejemplo, crear un manual de usuario de una biblioteca en que aparecen automáticamente las enlaces al manual de referencia de los objetos de que estamos hablando.

Incluir un documento HTML

A veces los documentos HTML no son tan simples para que podamos usarlo directamente con doxygen. Puede haber varias razones. Por ejemplo:

  • El documento HTML se quiere usar tal cual como una página de Internet.
  • El documento usa una hoja de estilo u otros enlaces. En este caso y el anterior no podemos quitar la cabecera.
  • El documento usa contenido dinámico con Javascript.
  • El documento usa contenido empotrado como vídeos o animaciones flash.

En todos estos casos no queremos perder las características del propio HTML. Lo que podemos hacer es crear un pequeño fichero dox con el contenido siguiente:

/** \page mi_otra_pagina_html Mi otra página HTML
\htmlinclude "mi_fichero.html"
(Este documento sólo está disponible en la versión HTML de la documentación.)
*/

Con esta fuente, doxygen crea una página en que incluye el documento HTML “mi_fichero.html”, pero sólo para la versión HTML de la documentación. Desgraciadamente no existe una etiqueta en doxygen, con que podemos escribir algo en todos los formatos menos HTML. Así aparece una página prácticamente vacía en los demás formatos. Sólo se ve la frase “(Este documento sólo está disponible en la versión HTML de la documentación.)“. Esta frase aparece también al final del documento HTML, pero visualmente se impone menos. Existen también comandos exclusivos para otros formatos como \latexonly, pero no podrán sustituir el contenido dinámico de una página HTML, desde luego.

Debemos añadir el directorio, donde guardamos los ficheros HTML a incluir, al EXAMPLE_PATH de la configuración de doxygen. Si no es posible que doxygen no encuentra los ficheros que incluimos.

La ventaja de incluir un documento HTML de esta manera es poder usarlo sin modificación y aprovecharse de toda la potencia que una página WEB ofrece. La desventaja es que doxygen no enlaza nombres de identificadores con el manual de referencia y en los formatos no HTML no aparece ningún su contenido. Sin embargo, en muchos casos esto no supone un problema, ya que no se crea una documentación en otro formato que HTML.

Una aplicación de este truco puede ser la inclusión de un manual de usuario u otro texto libre. Se puede escribir en un editor como Microsoft Word y guardarlo como una página HTML. Luego se incluye esta página mediante \htmlinclude en la documentación de doxygen. Así es posible mantener una documentación completa y actualizada en todo momento.

Una cosa que, por cierto, no funciona es usar el comando \link a un fichero interno para crear un enlace a este documento HTML en la documentación. El enlace, sí, estará en la documentación creada por doxygen, pero no el fichero que enlaza. Esto sólo se puede hacer para documentos con una URL de Internet pública.

Conclusión

Hemos visto dos maneras de incluir documentación adicional al manual de referencia que doxygen crea a partir del código. La capacidad de doxygen de interpretar muchas etiquetas HTML permite incluir documentos escritos en HTML en la documentación. Es una buena opción para documentos no interactivos. Para páginas HTML más complejos se ofrece incluir la página tal cual mediante \htmlinclude, que mantiene toda la potencia de una página interactiva, pero a coste de no poder verlo en los demás formatos que doxygen puede crear.

Referencias

A la hora de crear un documento es importante saber, qué formato usamos para generarlo. Muy a menudo resolvemos esta cuestión sin pensar más: Usamos Microsoft Word para escribir una carta y creamos un documento HTML para publicar algo en Internet. Otras cosas anotamos en un simple fichero de texto o quizá tenemos una razón de usar formatos menos populares como LaTeX – por ejemplo, si trabajamos en el ámbito de las ciencias naturales. Resolvemos esta cuestión sin pensar más, porque otros ya lo han pensado, o porque simplemente no es siempre tan importante.

En este artículo queremos reflexionar sobre las posibilidades de documentación que tenemos y por qué unos formatos son más adecuados (adecuados, no mejores) para unas tareas y otros para otras. Qué formato a escoger a la hora de crear documentos es desde luego importante a la hora de crear un documento de gran tamaño, que será usada por mucha gente o se actualice durante mucho tiempo. Hay formatos tan diversas como las necesidades que tenemos y aquí no pretendemos de dar a conocer a todos. Lo que presentamos es una presentación de conceptos a tener en cuenta a la hora de eligir una tecnología u otra.

Resumen de formatos y características

Antes de proceder veremos una tabla que resume el contenido de este artículo. En la primera columna están listados unos formatos para editar documentos y en la primera fila las carácterísticas que nos interesan.

Propiedades de diferentes formatos de documentación
Gráfico ASCII Gratis Orto­grafía Gramática Multi-Idioma Guiones
Microsoft Office (Sí)
Open Office (Sí)
LaTeX (Sí) (Sí)
HTML (Sí) (Sí) (Sí) (Sí)
DocBook (Sí) (Sí) (Sí) (Sí)
Texto en­riquecido (Sí) (Sí) (Sí) (Sí)
Texto simple (Sí) (Sí)

El significado de las características es el siguiente:

Gráfico
Existe un editor WYSIWYG, acrónimo inglés para What You See Is What You Get (Lo que ves es lo que obtienes). Tener está capacidad trae la ventaja que vemos ya editando como será nuestro documento final. El contrario de esto es deber editar un fichero fuente en un editor de texto y compilarlo en un formato final. Sí entre paréntesis en esto contexto quiere decir que se puede editar documentos con editores gráficos aunque el fundamento es un texto con códigos de control (como HTML).
ASCII
El formato está basado en un fichero ASCII (de texto) que se debe compilar (transformar) de alguna forma. Por ejemplo, un fichero LaTeX es un código fuente que necesita ser procesado por un programa de nombre TeX para convertirse en un documento de aspecto gráfico. El fichero fuente en sí se parece más a un código de programación. Hay varios formatos (OpenDocument y Texto Enriquecido) que tambien están basado en ficheros ASCII. Sin embargo, no están diseñados para modificar documentos con un editor de texto.
Gratis
Indica si es software libre y usa estándares abiertos. La mayoría de los formatos gratis están basados en estándares y programas de código abierto. Sí entre paréntesis en este contexto quiere decir que puede depender del uso. Un documento en formato DocBook, por ejemplo, necesita un compilador para convertirse en un documento legible. Dependiendo del tipo de documento legible que busco (página Web, PDF etc.) puede tocar pagar o lo consigo gratis también.
Ortografía
Tiene corrector de ortografía mientras edito. Los editores gráficos suelen tenerlo. Los formatos que se basan en un fichero de fuente en formato ASCII pueden ser editado con un editor que dispone de un corrector de ortografía o no. En este contexto se puede enteneder el sí entre paréntesis.
Gramática
Comprueba la gramática del texto editado. Es una herramienta muy útil para editar texto bien redactados especialmente en un idioma extranjero.
Multi-Idioma
Ofrece la posibilidad de usarlo con facilidad con mútliples idiomas. Un sí entre paréntesis en este contexto quiere decir que tiene la posibilidad pero hay que hacer algún esfuerzo más allá de descargar un fichero para conseguirlo (como descargar librerías adicionales o pagar por ello, por ejemplo).
Guiones
Tiene separación de palabras con guiones al final de la línea. Esto es algo imprescindible para generar documentos bonitos, sobre todo si tienen el margen derecho justificado. Sí entre paréntesis quiere decir que esta opción existe teóricamente, pero no está implementado con facilidad (como en HTML) o depende del editor que se usa.

Criterios para el formato adecuado

Para elegir bien el formato para nuestro documento debemos primero fijar los criterios según los cuales eligimos. Para expresarnos mejor, definimos familias de formatos a que nos referimos a partir de ahora:

  • Editores gráficos como Microsoft Office o OpenOffice que muestran el estado visualizado con cada tecla apretada.
  • Formatos de texto como HTML, DocBook o LaTeX que se basan en ficheros de texto.
Contenido gráfico

Si mi documento contiene muchas gráficas y debo constantemente actualizar el lay-out manualmente, entonces conviene usar un editor gráfico que mete todo en un fichero. Como formatos de texto no pueden incluir algo que no sea texto directamente, deben incluirlo mediante enlaces. De esta forma se debe mantener muchos ficheros y para ver el resultado final hace falta un proceso intermedio como la compilación en caso de LaTeX o la actualización del navegador en caso de HTML.

Conveniencia

Si no quiero perder tiempo a aprender un nuevo formato para editar documentos, entonces uso uno que ya conozco. En general es más fácil usar editores gráficos ya que son más intuitivos. Los formatos de texto son más fáciles a generar por programas de documentación automática.

Otro punto importante puede ser la corrección de errores lingüisticos. Un corrector de ortografía que sulinea todas las palabras que no conoce puede ser una ayuda para dejar el documento en un mejor estado desde el principio. Microsoft Office ofrece incluso un corrector de gramática. Desgraciadamente Microsoft Office viene con un número de idiomas bastante reducido. Según lo políglota que soy me pueden interesar correctores de muchos idiomas diferentes. Y finalmente puede influir también la ayuda en línea que suministra el programa que uso para entenderlo.

Tiempo de uso

¿Qué es la probabilidad que vaya abrir, imprimir o modificar el mismo documento en diez años? Si escribo una solicitud de empleo será cercano a cero, si escribo un diario cercano a uno. A priori nunca se sabe qué formato se hará obsoleto, es decir, ya no habrá programas que lean y muestran los contenidos del fichero correctamente. En general es menos probable que un formato popular y basado en un estándar abierto se hará obsoleto que uno de una aplicación específica. Para un uso de larga duración son, por lo tanto, recomendables los formatos abiertos y de texto.

Habrá más personas con el mismo problema si un formato popular se hace obsoleto, y será al menos teóricamente posible de escribir un conversor si el formato sea abierto, o sea, que se puede obtener la documentación necesaria para intepretar correctamente los contenidos del fichero. Una empresa con el peso de Microsoft puede aprovechar su formato no abierto para hacer incompatible documentos de diferentes versiones. Como tampoco vende versiones antiguas de su producto Office es posible que una empresa se ve obligada a comprar muchas licencias nuevas sólo para que un grupo de autores puede seguir trabajando en un mismo documento. Y aunque parezca poco probable hoy en día, también una empresa como Microsoft puede quebrar o abandonar el producto Office, por lo cual ya no habrá actualizaciones y mucho menos conversores para otro software popular en el futuro. La documentación sobre un formato abierto, en cambio, siempre sigue existiendo aunque caiga en desuso.

Si soy mando de una gran empresa podrá ser rentable optar por un formato complejo de un editor gráfico como OpenOffice y arriesgar encargar la programación de un conversor si hubiera la necesidad en algún momento.
Para aquellos con menos recursos serán fuertemente recomendados los formatos de texto, aunque sean más difíciles a usar. Un editor de texto es lo más básico y siempre habrá en uno en cualquier ordenador. Al contrario de los formatos binarios, los formatos de texto pueden ser leídos por seres humanos (aunque con dificultades) si ya no dispongo de ninguna herramienta informática que les sepa tratar. Esto puede ser crucial si sólo busco un nombre o número de teléfono en un documento viejo. Y, desde luego, siempre será más fácil convertir un fichero de texto a un formato más moderno que un fichero binario.

Accesibilidad

No siempre lo mejor es lo más adaptado, sobre todo no adaptado a las necesidades de los lectores. Aunque tendré que actualizar mi currículum vitae durante la vida y sería preferible hacerlo en un formato abierto, los departamentos de recursos humanos siempre me lo piden en formato de Microsoft Word. Si el destinatario sólo quiere leer mi documento, entonces puedo crearlo a mi conveniencia y convertir al formato PDF, que practicamente todos los ordenadores pueden leer. Pero si el destinatario también quiere editarlo, entonces será mejor no obligar a descargarse y entender un software complicado aunque sea el más adecuado para el tipo de documentación que me pide.

Un punto importante puede ser la portabilidad del documento entre diferentes plataformas: Hay navegadores de Internet para Microsoft Windows, para Linux, para Unix y para Apple, pero Microsoft Office no existe en versión Linux. Los formatos de texto pueden ser editados HTML y LaTeX con cualquier ordenador.

Otra cosa que hay que tener en cuenta son las versiones de un mismo programa. Es posible que no todo el mundo tiene la última versión y, por lo tanto, no podrá ver todas las funcionalidades que podrías haber incluído. Optar por un estándar simple ayuda a que más personas puedan verlo. Y lo mismo vale teniendo en cuenta que no todo el mundo tiene una conexión de Internet rápida. Es posible que otros jamás podrán ver tu documento súper bonito pero con poco contenido, simplemente porque no consiguen descargarlo.

Integridad física

¿Ya te ha pasado que quisiste deshacer un cambio en una plantilla de formato en Microsoft Word y buscabas un botón heredar propiedad del padre? Una lista de problemas que you tuve con Microsoft Word durante mi proyecto fin de carrera:

  • No se podía guardar un fichero porque no hubo espacio en el disco duro. El fichero tenía un tamaño de unos tres megabyte y el espacio en el disco duro eran 500. Descubrí que una fórmula matemática se había convertido en un objeto desconocido.
  • Tampoco se podía abrir el fichero por falta de memoria. Conseguí seperar el fichero en múltiples (uno para cada artículo) y podría poner los número de página a mano.
  • En las listas con viñetas (como en la que estás leyendo ahora mismo) desaparecieron las viñetas y no hubo forma de convencer a la aplicaciones que los pusiese otra vez.

Es posible (y me ha pasado), que la falta de memoria hace también imposible trabajar con otros procesadores de texto como LaTeX, pero hay dos puntos diferentes muy importantes:

  1. Microsoft Word guarda un documento en un fichero binario. Si sólo añades, quitas o modificas un byte con un hexeditor puede ser que ya no se deja abrir. No hay forma de reparar un fichero .doc a mano.
  2. Si Microsoft Office te guarda algo mal en tu documento por el error que sea, te habrá sobreescrito la vieja versión que aún funcionaba. En los formatos de texto como LaTeX, sólo editas el fichero fuente. Cualquier representación de esta fuenta será guardado en otro fichero. Aunque este fichero generado será degenerado, siempre es posible que vayas con tus ficheros fuente a otro ordenador mejor (o consultas con una persona que sabe mejor) y intentas generarlo otra vez.

En fin, la integridad física de un fichero indica hasta que grado se puede usar aunque contenga un error o fue parcialmente destruido. En general no hay forma de reparar un fichero binario. Por esto ya no se hace. La versión actual de Microsoft Office y OpenOffice guardan ahora sus contenidos en varios ficheros de texto en formato XML que se comprimen en un archivo ZIP. Que la extensión de Microsoft Word no es ZIP sino DOCX facilita relacionar los documentos con la aplicación. Pero puedes probar cambiar la extensión de un fichero DOCX a ZIP, y entonces puedes abrirlo con un archivo ZIP y ver sus contenidos.

Para los más preocupados es recomendable no usar editores gráficos, porque lo que tú editas no es lo que realmente se guarda – sino sólo una traducción (mayoritariamente correcta) de lo que editas. Sólo en los formatos de texto editas tú y tólo tú.

Medio de publicación

No es lo mismo si quiero escribir un libro o imprimir un texto a crear una página Web. La mayoría de los formatos están dedicados a publicar un documento en un medio específico aunque no exclusivamente. Los procesadores de texto sirven sobre todo para imprimir algo en papel, el HTML se inventó para mostrar algo en pantalla. Hoy en día, se pueden usar muchos formatos en muchos ámbitos aunque sigue haber una preferencia para un determinado uso.

La tendencia hoy en día es publicar un mismo documento en formatos diferentes: en papel, en pantalla e incluso por voz. Todo esto a partir de un mismo documento fuente. Con este propósito se definó el estándar de DocBook, que sólo define contenidos y no la representación de un documento.

Procesado automatizado

Muchas veces interesa crear documentación de forma automatica a partir de código de un lenguaje de programación. Esta documentación se puede mezclar por otra editada por seres humanos, por ejemplo un tutorial sobre una biblioteca, donde se quiere entrelazar los nombres de clases, métodos y variables con la referencia creada por el programa de documentación automatizada. En estos casos es casi imperativo el uso de formatos de texto. Por ejemplo, phpDocumentor, un programa de documentación automatizada para el lenguaje de programación PHP pueden incluir textos editados por humanos, si están escritas en el formato DocBook.

Los formatos en detalle

Queremos dar una vista detallada sobre los distintos formatos mencionados en el resumen. Este apartado tiene en consecuencia una sección para cada formato.

Microsoft Office

Microsoft Office es la elección para quienes quieren usar y no pensar. Todo está automatizado y con dos clicks ya tienes impreso tu documento. A un click la ayuda, corrección de ortografía y el único con correción de gramática convierten Microsoft Office en algo fácil de usar. Lo bueno tiene precio, y este es bastante alto. Si uno quiere ahorrárselo, entonces será recomendable usar OpenOffice. Lo malo es que casi todas las empresas prefieren no ahorrar y al final tú también necesitas Microsoft Word sólo para tener tu currículum en formato Word.

Puesto el caso que ya tienes una licencia, Microsoft Office es una buena elección para editar algo a corto plazo. Es decir, algo que vas a terminar a editar en al menos medio año y luego ya no te duele que no se pueda usarlo con la próxima versión. También conviene para compartir documentos con personas que no saben tanto de ordenador y ya tienen suficiente con conocer a un programa. En cambio, los productos de Microsoft no suele haber en versiones para Linux o Unix.

Si piensas editar un documento de gran tamaño y complejidad como un texto con muchas fórmulas matemáticas, entonces no es recomendable usarlo. Lo mismo vale si no quieres gastarte dinero en la licencia (o hacer cosas ilegales para conseguirla). Si te importa que puedas modificar y usar tu documento durante muchos años, es preferible no usar productos propietarios (no abiertos), ya que puedan volverse incompatible sin previo aviso en la próxima versión.

OpenOffice

OpenOffice tiene la misma funcionalidad que Microsoft Office, a que se parece mucho en su uso. Sin embargo, tiene una diferencia importante en el precio: Es gratis. Es un proyecto de código abierto, donde puedes participar con tus propias rutinas; si quieres. Como no hacen dinero vendiéndote la última versión, tampoco hay necesidad de incluir más incompatibilidades entre versiones que necesario.

Es recomendable usar OpenOffice para el uso diario igual como Microsoft Office. Por ser de código abierto es probable que su formato será legible también en el futuro, aunque tampoco hay garantía de que este proyecto de software será abandonado en algún momento. Una desventaja es que casi nadie tiene OpenOffice instalado y, por eso, no se puede usar su formato nativo para compartir documentos. No obstante, OpenOffice tiene un conversor para documentos de Microsoft Office. Sin embargo, no es recomendable editar un mismo documento con los dos Office. Un conversor sirve para visualizar y transformar contenido, pero no para editar un documento con dos aplicaciones distintas, ya que no todas las características se pueden convertir. Un documento de Microsoft Word es similar a uno de OpenOffice, pero no igual.

Para mí, OpenOffice es la elección cuando quiero editar un texto para mí mismo. Puede ser el estándar interna de una empresa que quiere ahorrarse licencias costosos.

Existe una versión de OpenOffice que se llama OxygenOffice. Funciona igual pero aporta muchos ficheros adicionales como clipart, plantillas, diccionarios, imágenes y sonidos.

LaTeX

Lo primero que llama la atención en el procesador de texto LaTeX es su forma peculiar de escribirse. El sistema de base de llama TeX y fue inventado para rellenar una hoja de papel con caracteres. Como es un formato de texto, todo lo que no sea una letra para imprimir debe ser una palabra que comienza con la barra invertida. Hay un comando para añadir un línea de pie \footline, donde se puede añadir el número de la página \pageno y cambiar a una fuente negrita con \bf.

Hubo a quien todo esto pareció demasiado complicado y se aprovechó de un gran capacidad del sistema TeX: las macros. Se pueden definir nuevos comandos (con \) que luego se reemplazan por el contenido. Estas macros también permiten parámetros de forma que se podría definir un tipo de documento libro, que tiene páginas pares e impares diferentes, con tanto espacacio hacia arriba y abajo y admite como parámetro el tamaño de la fuente. Todo esto ya lo hecho alguien y llamó el resultado LaTeX.

LaTeX tiene comandos que están más cercano a lo que quiere el usuario y por eso es relativamente fácil empezar a usarlo – con énfasis a relativamente. Lo que no cambia es la abundancia de barras inversas a que cuesta acostumbrarse. Ahora la pregunta por qué alguien quisiera usar un sistema así.

Pues, el resultado es simplemente más bonito. La diferencia con los editores gráficos ya no es tan grande ahora que hace años, pero LaTeX sigue siendo la elección para quién quiera escribir textos con muchas fórmulas matemáticas. Porque salen más bonitas y LaTeX ofrece muchos símbolos matemáticos.

Otra ventaja es que las fórmulas no son objetos aparte del texto como en los editores gráficos. No hace falta abrir ningún editor especial para editarlas. Son texto como lo demás, y cambiar el tamaño de la fuente de todo el documento es tan fácil como cambiar un parámetro en la definición de la clase del documento. Con Microsoft u Open Office habría que ir una a una y cambiarlo manualmente.

LaTeX es un formato de texto que tiene, por lo tanto, ficheros fuente más pequeños que los documentos de un editor gráfico. Desventajas son que la instalación es relativamente complicada y que hay que compilar los ficheros fuente cada vez que se cambie algo. El resultado de esto es un gran número de ficheros generados que puede agobiar a quién adora tener sus directorios limpios. En cambio, la funcionalidad de macros es muy potente: se pueden crear nuevos estilos y diseños de página más allá de lo inicialmente pensado. También permite escribir ecuaciones con palabras humanas. Por ejemplo, para visualizar la ecuación U = R·I se puede escribir en el fichero fuente \tension = \resistencia·\corriente si se ha definido anteriormente

\newcommand{\tension}{U}
\newcommand{\resistencia}{R}
\newcommand{\corriente}{I}

Si siempre uso la macro \tension en lugar de U, podría cambiar la letra a V en todo el documento sólo cambiando la definicón de la macro \tension.

HTML

HTML (HyperText Markup Language) es la base de cualquier documento que vemos en un navegador de Internet. Podemos visualizar un fichero HTML también cuando no esté en Internet sino en nuestro disco duro. HTML ha sido diseñado para Internet y permite enlaces a otros documentos o contenido en otros ordenadores. No es difícil incluir en tu documento una imagen que reside en un servidor en otro continente.

Mientras los principios de HTML eran dedicados a mostrar documentos de Internet en un navegador, hay una tendencia de separar contenido de la representación de contenido. Idealmente un documento HTML sólo define qué texto contiene un título, que texto contienen los párafos que siguen, que son las contenidos de una tabla, pero no hay ninguna referencia sobre la fuente, los colores, la sangría o las viñetas en las listas que se usan. Todo esto define un invento más reciente que se llama CSS (Cascading Style Sheet – hojas de estilo en español).

Este proceso todavía no ha finalizado, pero la intención es clara: Que HTML será un formato libre de información representativa, por lo cual el mismo documento puede ser convertido en diferentes representaciones para pantalla, papel o incluso sonido con diferentes hojas de estilo. Esto trae también la ventaja que un escritor sin estilo puede dedicarse a escribir sus ideas y dejar el resto a un estilista sin ideas. Contenido y representación todavía no se dejan separar de todo, pero será el futuro.

HTML es un formato muy popular y es difícil encontrar un editor que no sepa algo de HTML. Microsoft Office y OpenOffice importan y exportan HTML, un documento HTML puede ser visualizado en cualquier navegador y HTML es probablemente el mejor formato para hacer algo para la eternidad. Hay muchos editores gráficos para quien no quiera editar un fichero de texto con códigos de comando <>. Aunque HTML es a veces demasiado simple con comparación con lo que ofrecen los procesadores de texto, se puede optar que el futuro lo resuelve.

Como ejemplo ponemos la númeración de los títulos: HTML no lo permite y habría que numerar cada encabezado manualmente. Sin embargo, la versión 2.1 de los Cascading Style Sheets permite añadir un esquema de númeración de títulos. Podemos esperar que habrá aún más utilidades en el futuro.

DocBook

La separación entre contenido y representación se ha llevado a completo con el estándar DocBook. El código de un documento DocBook tiene un aspecto similar a HTML por tener un formato XML, pero ofrece muchos más componentes: todo lo que uno podría necesitar en una tésis de doctorado o manual de usuario.

Como el formato DocBook sólo contiene el contenido del documento, le falta un herramienta que lo represente, es decir, que lo convierta en una página HTML o un documento PDF o lo que sea. Por lo tanto, DocBook no es una buena elección si sólo pienso tener una representación. La idea de DocBook es que puedo generar representaciones muy diversas a partir de una sola fuente, pero necesito crear estas representaciones anteriormente. Como DocBook es un formato de texto, es muy bueno para crear documentación automatizada que luego se quiere exportar como páginas de Internet, en formato PDF y como fichero de audio.

Texto enriquecido

Texto enriquecido (Rich Text Format en inglés) es un formato de texto. Sin embargo es tan confuso que no habrá quién lo editaría con un editor de texto. (Para comprobarlo basta guardar un documento de Microsoft Word como fichero RTF y abrirlo en el bloc de notas.)

Este formato fue pensado para editar algún texto bonito con texto en negrita y cursiva sin guardar el tipo de contenido detrás de la representación. Es decir, el formato sabe la fuente de la letra pero no sabe qué corresponde a un título y qué a un texto normal y corriente. Por lo tanto, no sirve para escribir grandes obras, pero, sí, para crear un texto visualmente agradable que se deja abrir en muchos editores.

Más que un formato para editar y guardar, es un formato para exportar. Por ejemplo, se puede convertir los contenidos de un DocBook en un fichero de texto enriquecido para luego imprimirlo. Como texto enriquecido es un formato de texto, permite cambios fáciles a base de cadenas de texto por un programa de ordenador.

Texto simple

Un texto simple es lo que muestra el bloc de notas en Microsoft Windows: una secuencia de caracteres. Aunque un texto sin más tiene un aspecto aburrido, puede ser lo mejor en determinadas circunstancias.

Un fichero de texto es lo más portable posible. Siempre habrá un programa que podrá leerlo y no es posible conseguir ficheros más pequeños con el mismo contenido. No requiere ningún programa especial para ser leído. Es eterno. Y los más rápido a la hora mostrarlo en pantalla también.

Desde hace años uso un fichero de texto como mi agenda. Desde luego no es tan fantástico que una PDA o un organizador de eventos especializado, pero cabe en un disquete, se puede leer en cualquier ordenador (en el trabajo) y cuando se acabe la vida (de la batería) de la PDA no necesito copiar manualmente todos los datos porque no son compatibles con la PDA nueva. El formato de texto simple es el más adecuado cuando necesito algo simple y rápido.

Conclusión

Hemos visto formatos muy diferentes para crear documentación. Ahora ¿cómo eligir? Para ello eliges los escenarios que más se ajustan a tu caso. En general no hay el mejor formato. Cada uno tiene sus ventajas e inconvenientes y será a veces una cuestión de gusto cual usas. Y, en fin, hay muchos conversores de un tipo de formato a otro.

Necesidad de documentación y su formato idóneo.
Mi problema Mi formato
Odio a la programación y códigos crípticos. Microsoft Office, OpenOffice o Texto Enriquecido.
Quiero íntegridad física y un formato de texto. HTML, LaTeX, DocBook, Texto simple.
Rápido y simple. Texto simple, HTML. Dependiendo del editor asociado: Texto Enriquecido.
No quiero ni pagar ni piratear (y que sea de código abierto). Todo excepto Microsoft Office.
Quiero un formato popular. HTML. Para el sistema operativo Microsoft Windows: Microsoft Office y Texto Enriquecido.
Quiero imprimir en papel. Microsoft Office, OpenOffice, LaTeX
Quiero las fórmulas matemáticas más bonitas. LaTeX. Microsoft Office y OpenOffice tienen editores de fórmulas.
Quiero verlo en pantalla y que sea interactivo. HTML. En menor medida Microsoft Office y OpenOffice.
Quiero exportar mi documento a muchas representaciones diferentes. DocBook, HTML.
Quiero documentar mi programa de ordenador. (Sólo para quienes ponen comentarios en el código.) DocBook, HTML, LaTeX.
El usuario de mi programa debe poder imprimir la página Web que le muestro o convertirla en un PDF. HTML, LaTeX, Texto Enriquecido, texto simple

Referencias

Formatos de Documentación
Herramientas de documentación automatizada
Artículos relacionados en este blog

Doxygen es una herramienta de documentación automatizada muy potente. Como muchos programas viene con la configuración para el inglés americano por defecto. Por eso puede haber problemas a la hora de procesar bien comentarios que usan letras con acentos como suele haber en español y muchos otros idiomas.

Una solución al problema es guardar los ficheros con la codificación UTF-8, que es la que viene por defecto también en phpDocumentor. Sin embargo, doxygen permite especificar explícitamente qué codificación a usar.

Si usas el interfaz gráfico Docwizard, entonces puedes pinchar en la pestaña “Expert”, y luego en el menú de los “Topics” seleccionas “Input”. A la derecha hay un campo que se llama INPUT_ENCODING. Cambia el valor (“UTF-8” por defecto) a la codificación de tus ficheros fuente. Para el español suele ser la codificación ISO-8859-1. Obviamente sólo puedes usar una codificación de caracteres para un proyecto.

Si no usas el interfaz gráfico puedes buscar por la cadena de texto INPUT_ENCODING en el fichero de configuración.

Si no estás seguro qué codificación a elegir, entonces puedes visualizar la documentación generada y jugar con la codificación de los caracteres del navegador hasta tu documentación  salga bien. La codificación puedes cambiar (en Mozilla Firefox) con el menú View (Ver) -> Character Encoding. Cuando haces estas pruebas fíjate en los textos que has escrito tú en la documentación; y no en los títulos que añade doxygen. Cuando pones la codificación correcta en el campo INPUT_ENCODING, tanto los textos generados a partir de los comentarios como los que añade doxygen saldrán con los acentos bien. Recuerda volver poner tu navegador a autodetectar la codificación.

Por cierto, también se puede modificar la codificación del fichero de configuración de doxygen. En la pestaña “Expert” seleccionas en el menú “Topics” el punto “Project”. A la derecha hay un campo que se llama DOXYFILE_ENCODING. Cambia el valor (“UTF-8” por defecto) a la codificación desdeada.

Referencias

Qué es

Lo que javadoc es para Java, phpDocumentor es para PHP: Una herramienta para generar documentación a partir del código fuente. (Ver artículo sobre
Documentación automatizada.)

Por ser dos proyectos separados, phpDocumentor no es automáticamente compatible con una nueva versión de PHP. Por ejemplo, yo tuve problemas con phpDocumentor 1.4.3 cuando instalé PHP 5.3 y volví a la versión 1.4.2 que funcionaba aunque con muchas advertencias.

Una alternativa a phpDocumentor es Doxygen que puede también documentar código PHP. Una diferencia es que doxygen es un programa, mientras phpDocumentor es una colección de código en PHP. Es decir, genera la documentación con el mismo PHP que usas para ejecutar tu propio código PHP. Por eso necesitas tener también PHP en tu máquina para poder usar phpDocumentor. Sin embargo, no necesitas instalar un servidor web.

Como instalar

phpDocumentor no es un programa sino un código fuente y, por eso, no tiene instalador. Es un archivo que descomprimes en un directorio. Para usar phpDocumentor debes abrir el fichero phpdoc.bat (en Windows) y especificar la ruta a php.exe en la variable phpCli. Por ejemplo

SET phpCli=C:\Program Files\PHP\php.exe

Como usar

Para un proyecto en concreto conviene crearse un script en que especificas todas las opciones de phpdoc.

El siguiente script es un ejemplo. Lo he utilizado para generar la documentación del mismo phpDocumentor. Antes de usarlo hay que ajustar los directorios de entrada y salida y de la instalación de PHP.

echo Generate automatic documenation for phpDocumentor
echo Version from 12.6.2009

rem Directory list must be without spaces between the coma
set phpdoc_dir="C:\opt\PhpDocumentor"
set source_dir="C:\opt\PhpDocumentor"
set target_dir="C:\doc\phpDocumentor"
set title="phpDocumentor Documentation"
set projects=phpDocumentor
rem set output="HTML:frames:default"
rem set output="HTML:frames:earthli"
rem set output="HTML:frames:l0l33t"
 set output="HTML:frames:phpdoc.de"
rem set output="HTML:frames:phpedit"
rem set output="HTML:frames:phphtmllib"
rem set output="HTML:frames:DOM/default"
rem set output="HTML:frames:DOM/earthli"
rem set output="HTML:frames:DOM/l0l33t"
rem set output="HTML:frames:DOM/phpdoc.de"
rem set output="HTML:frames:DOM/phphtmllib"
rem set output="HTML:frames:DOM/phphtmllib"
rem set output="HTML:Smarty:default"
rem set output="HTML:Smarty:HandS"
rem set output="HTML:Smarty:PHP"
rem set output="CHM:default"
rem set output="PDF:default"

cd %phpdoc_dir%
call phpdoc -d %source_dir% -t %target_dir% -ue on -ti %title% -pp off -po %projects% -o %output% -s off
rem pause
exit

rem These are comments, but they will not be executed because the scripts exists before
rem use phpdoc -h to see this

  -f    --filename                name of file(s) to parse ',' file1,file2.
                                  Can contain complete path and * ? wildcards

  -d    --directory               name of a directory(s) to parse
                                  directory1,directory2

  -ed    --examplesdir            full path of the directory to look for
                                  example files from @example tags

  -tb    --templatebase           base location of all templates for this
                                  parse.

  -t    --target                  path where to save the generated files

  -i    --ignore                  file(s) that will be ignored, multiple
                                  separated by ','.  Wildcards * and ? are ok

  -is    --ignoresymlinks         ignore symlinks to other files or
                                  directories, default is off

  -it    --ignore-tags            tags to ignore for this parse.  @package,
                                  @subpackage, @access and @ignore may not be
                                  ignored.

  -dh    --hidden                 set equal to on (-dh on) to descend into
                                  hidden directories (directories starting with
                                  '.'), default is off

  -q    --quiet                   do not display parsing/conversion messages.
                                  Useful for cron jobs on/off default off

  -ue    --undocumentedelements   Control whether or not warnings will be shown
                                  for undocumented elements. Useful for
                                  identifying classes and methods that haven't
                                  yet been documented on/off default off

  -ti    --title                  title of generated documentation, default is
                                  'Generated Documentation'

  -h    --help                    show this help message

  -c    --useconfig               Use a Config file in the users/ subdirectory
                                  for all command-line options

  -pp    --parseprivate           parse @internal and elements marked private
                                  with @access.  Use on/off, default off

  -po    --packageoutput          output documentation only for selected
                                  packages.  Use a comma-delimited list

  -dn    --defaultpackagename     name to use for the default package.  If not
                                  specified, uses 'default'

  -dc    --defaultcategoryname    name to use for the default category.  If not
                                  specified, uses 'default'

  -o    --output                  output information to use separated by ','.
                                  Format: output:converter:templatedir like
                                  "HTML:frames:phpedit"

  -cp    --converterparams        dynamic parameters for a converter, separate
                                  values with commas

  -ct    --customtags             custom tags, will be recognized and put in
                                  tags[] instead of unknowntags[]

  -s    --sourcecode              generate highlighted sourcecode for every
                                  parsed file (PHP 4.3.0+ only) on/off default
                                  off

  -j    --javadocdesc             JavaDoc-compliant description parsing.  Use
                                  on/off, default off (more flexibility)

  -p    --pear                    Parse a PEAR-style repository (package is
                                  directory, _members are @access private)
                                  on/off default off

  -ric    --readmeinstallchangelogSpecify custom filenames to parse like
                                  README, INSTALL or CHANGELOG files

You can have multiple directories and multiple files, as well as a combination
of both options

En la carpeta HTML nuevamente generado debes abrir el fichero index.html para ver la página principal de la documentación. La más práctico es crearse un enlace fuera del directorio con un nombre significativo como “Documentación de bla bla”.

Puedes usar letras con acentos y otras letras no ASCII si guardas el fichero fuente (con el código) con la codificación UTF-8 (con BOM). En general no es mala idea guardar tu código como UTF-8 en lugar del habitual ISO-8859 si quieres usar otros idiomas que el inglés en los comentarios, porque phpDocumentor (y también doxygen) codifican su salida HTML en UTF-8.

phpDocumentor tiene diferentes convertidores. Cada uno compila la documentación en un formato y tema diferente (HTML, PDF, CHM). La página web de phpDocumentor muestra ejemplos de los diferentes temas visuales que permite la documentación en HTML.

Crear la documentación de phpDocumentor y tutoriales

Como ya he mencionado más arriba, phpDocumentor puede crear su propia documentación. Los ficheros fuente de esta documentación están en una subcarpeta “tutorials”. Sin embargo, debes especificar el directorio raíz de phpDocumentor como directorio de entrada a phpdoc, para que se compilen estos tutoriales. (phpDocumentor no procesa documentación en “tutorials” que no esté vinculado a algún código fuente. No puedes compilar sólo tutoriales.) Como proyecto debes especificar “phpDocumentor”. (Ver ejemplo abajo.)

Esta subcarpeta “tutorials” es también un ejemplo de como escribir documentación que no está directamente vinculada a algún objeto dentro del código. Estos tutoriales están escrito en un formato reducido de DocBook. Los elementos DocBook que se compilan están listado en la sección [ppage] del fichero options.ini que viene con cada convertidor. Por ejemplo, mi tema favorito “HTML:frames:earthli” está configurado por el fichero Converters/HTML/frames/templates/earthli/options.ini. Cada convertidor/tema tiene su fichero de configuración options.ini en una carpeta diferente.

Conclusión

phpDocumentor es una herramienta potente para crear documentación a partir de código fuente PHP. El formato de comentarios de documentación es fácil de aprender por ser muy parecido al formato de javadoc. (Ver lista de características de phpDocumentor.)

Una desventaja es que cuesta hacer phpDocumentor funcionar. Es un problema que desaparece una vez familiarizado con la herramienta, pero que puede causar frustración al principio. También existe una interfaz gráfica para generar la documentación pero que requiere un servidor web propiamente configurado. No está mal pero no quita el problema de tener que leer mucha documentación antes del primer éxito. En comparación el wizard de doxygen es bastante más fácil de usar.

Además, doxygen entiende varios lenguajes de programación, aunque no es capaz de ofrecer diferentes temas. Aún así vale la pena reflexionar sobre qué herramienta usar.

Referencias

  • phpDocumentor – la herramienta descrita en este artículo
  • Doxygen – una alternativa a phpDocumentor
  • javadoc – un sistema de documentación para Java.
  • PHP – el lenguaje de programación que phpDocumentor documenta.
  • DocBook – un formato para escribir textos sin especificar su aparencia y que phpDocumentor usa para la documentación libre (tutoriales).

En muchas ocasiones se pide un manual de referencia del código. Esto es especialmente importante a la hora de crear una librería que esté ideada para que otro programador la use en una aplicación final. Este manual engloba de alguna forma un trabajo doble: hay que explicar bien el funcionamiento de cada función en el código mismo y luego repetir la misma información en un documento de texto.

De este trabajo pueden encargarse sistemas de documentación automáticos. Leen el código y extraen la información necesaria para generar la documentación. Muchas veces permiten varios tipos de documentos de salida: en formato HTML, en formato PDF, como fichero de HTML comprimida (CHM) o en formato “Rich Text”.

Probablemente el más influyente de estos sistemas es javadoc. Fue incluido en el entorno Java de Sun como una parte integral del sistema y ha marcado desde entonces el formato de los comentarios de documentación. El programa de más uso es probablemente doxygen, ya que puede entender la sintaxis de muchos lenguajes, muy especialmente de C++. Para PHP es recomendable usar phpDocumentor.

A todos estos sistemas es común que requieren un marcador especial para los comentarios que se exportan del código a la documentación final. El más extendido es el de javadoc que marca los comentarios entre /** y */. Nota que es nada más que un comentario al estilo /**/ donde la primera letra es un asterisco. Sin embargo, para el sistema de documentación, el segundo asterisco en /** lo marca como un comentario de documentación cuyo contenido será procesado por el sistema de documentación automatizado.

Dentro de este bloque están permitido una multitud de etiquetas (tags en inglés) que dependen del objeto documentado, por ejemplo si es un fichero una clase o una función. La declaración de una función podría parecerse a algo como esto:

/**
 * La primera frase es un título/resumen de la función. Después del
 * punto que delimita la primera frase comienza la documentación
 * detallada. Características especiales están marcadas con una
 * etiqueta.
 * @param parametro El parámetro de la función.
 * @return La función devuelve un resultado.
 */
int mi_funcion(int parametro);

Guarda tus ficheros fuentes en Unicode si quieres tener acentos correctos en la documentación. Esto vale al menos para phpDocumentor.

Los sistemas de documentación sólo documentan declaraciones, objetos y tipos globales, ficheros y inclusiones. No documentan el cuerpo de una función ya que se supone que no es algo importante en un manual de referencia. Sin embargo ofrecen una etiqueta @internal con información interna, que sólo se compila con un cierto flag activado. De la misma forma se puede documentar o no variables y métodos privados.

Es cierto que los sistemas de documentación requieren algún esfuerzo al principio para instalar y entenderlos. Sin embargo, una vez superado esta fase ofrecen tener una documentación actualizada prácticamente en tiempo real que con sus enlaces y agrupaciones son una ayuda incluso para el autor durante el desarrollo. El entorno Eclipse ya incluye un enlace para mostrar la documentación de doxygen para código de C++.

Escribe tu dirección de correo electrónico para suscribirte a este blog, y recibir notificaciones de nuevos mensajes por correo.

Únete a otros 52 seguidores

Archivos

diciembre 2018
L M X J V S D
« Nov    
 12
3456789
10111213141516
17181920212223
24252627282930
31