You are currently browsing the tag archive for the ‘formas de trabajar’ tag.

Cuando empezamos con un nuevo proyecto, puede surgir la pregunta si se modifica un código viejo o se empieza desde cero. Reciclar código viejo para un nuevo proyecto ahorra tiempo, porque el código viejo ya está escrito y funciona. Escribir código otra vez también ahorra tiempo, porque es específico a lo que está pedido en el nuevo proyecto y un programador no necesita entender un código viejo difícil de comprender.

El ahorro de verdad está entre restaurar proyectos históricos y reinventar la rueda. Así la cuestión es ¿dónde está el punto óptimo entre reciclar y reinventar? Como en muchas ocasiones, no hay una respuesta fácil y, por lo tanto, no la voy a dar. En este artículo presento a condiciones de entorno a tener en cuenta a la hora de decidir si modifico lo viejo y empiezo de nuevo.

Un criterio es la calidad de documentación. Si un programador quiere aprovechar código de otro, no tendrá más remedio que entenderlo. Una buena documentación, que incluso incluye un razonamiento sobre el diseño y el uso de la biblioteca, es una gran ayuda. Entender código sin documentación sólo es beneficioso para secciones pequeñas de código. De otra forma existe el riesgo de pasar mucho tiempo para entender algo que posiblemente ni se puede usar.

En este contexto conviene saber que la herramienta doxygen permite generar gráficos de llamdas de funciones y herencia de clases a partir de un código existente. Doxygen permite llamar a una herramienta específica para la creación de grafos que se llama DOT.

A veces importa que se puede probar un software cuanto antes – especialmente donde se desean hacer pruebas exhaustivas como en la aeronáutica o la medicina. Otra motivación puede ser querer tener un prototipo funcional en cada momento. Entonces se intenta conseguir un código que compile y haga algo aunque sea poco. En este entorno puede ser preferible partir de un proyecto antiguo que funciona y modificarlo hasta que cumpla las nuevas especificaciones sin que deje de ser un programa funcional en ningún momento.

Algo importante a la hora de reutilizar código viejo es el grado de similitud entre el funcionamiento real y el funcionamiento deseado. Poder utilizar una biblioteca tal cual como es, es un argumento poderoso para utilizar el código viejo. Si, en cambio, hace falta tocar la mitad de las funciones, entonces mejor se aprovecha nada más que el fichero de cabecera.

De hecho, reciclar código no significa necesariamente copiarlo todo. La estructura de datos, la interfaz, un bucle o un comentario de documentación: es perfectamente válido empezar con un proyecto vacío y rellenarlo paso a paso con elementos de un proyecto antiguo. Esta es una manera muy útil cuando ya se sabe que el proyecto viejo contiene muchas partes útiles aunque el programador todavía se pierde entre tantas funciones. A la hora que avanza con su proyecto nuevo, entiende mejor las necesidades y puede buscar más eficazmente lo que necesita en el código viejo. En este caso el proyecto antiguo sirve más bien como un código ejemplo que un programa ya completo.

En general suele ser un buen compromiso utilizar lo viejo si cuesta poco utilizarlo y hacerlo nuevo en el caso contrario. Muchas veces no se cambia sólo la funcionalidad sino, además, otras circunstancias de contorno. En lugar de una conexión de puerto serie se usa un puerto USB, el sistema operativo usa 64 bits y no 32, el estilo de código de ahora es mejor que el utilizado en el código antiguo o quizá se piensa crear la aplicación como una página web y no un fichero ejecutable. En corto: si ya te toca tocar código viejo, hazlo de forma contundente.

Hemos visto que el grado de documentación, la necesidad de hacer pruebas o tener prototipos son circunstancias importantes de modificar lo viejo en lugar de empezar de nuevo. Por la similitud entre lo que está hecho y lo que se quiere hacer se elige hasta que grado se copian componentes antiguas: de módulos enteros via apartados de código a meramente inspiraciones para el nuevo proyecto.

Referencias

Anuncios

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

Una herramienta de control de versiones tiene un cierto potencial de adicción, ya que es difícil de dejar de usarlo cuando una vez se ha conocido sus ventajas. En este artículo queremos hablar qué ficheros conviene guardar en un control de versiones y cuando conviene no usarlo. “No usar un control de versiones” significa guardar los ficheros en el sistema de ficheros de sistema operativo, es decir en los directorios de toda la vida.

Describo en otro artículo lo que es un control de versiones. En este artículo asumo que el lector ya lo sabe.

En el artículo anteriormente mencionado defino las dos razones de usar un control de versiones, que son:

  1. Ayuda a que varios programadores pueden trabajar en paralelo.
  2. Permite mantener varias versiones de un mismo programa a la vez.

Una conclusión de esto es que no se usa un control de versiones si no se da al menos una de estas condiciones, ya que no vale la pena usar una herramienta adicional si no trae beneficio. No se pueden acceder ficheros bajo el control de versiones excepto con la misma herramienta y está puede tener problemas de compatibilidad con versiones nuevas del sistema operativo como cualquier otro programa. Tampoco es fácil añadir espacio cuando el repositorio ya ha llenado el disco duro entero. Una carpeta simple, por lo contrario, es fácilmente manejable en cualquier plataforma.

La consecuencia de no programar en paralelo es bastante obvia: un sólo programador no corre riesgo de no poder trabajar por culpa de otro. Mientras uno trabaja sólo es mucho más fácil guardar todos los ficheros en las carpetas habituales, aunque eso sí: organizando los ficheros para al menos teóricamente será fácil subirlos a un control de versiones. Nunca sabes si algún día habrá otro programador contigo.

O que habrá múltiples versiones. Mantener múltiples versiones es algo habitual en proyectos grandes. Mientras el cliente prueba una versión, los programadores ya desarrollan la próxima. Si es un software que al menos en principio cualquiera pueda descargar y usar, entonces conviene mantener el código bajo un control de versiones, ya que siempre habrá varias versiones en uso. El caso contrario es un software a medida.

Una vez entregado el software a medida al cliente funcionando, nadie se interesará por un estado intermedio durante el desarrollo. Hay una versión final y punto. Entonces se guarda esta última versión en carpetas del sistema operativo y se puede liberar el espacio en el control de versiones. Si el cliente un día quiere un cambio, se puede volver a subirlo – pero entonces a una herramienta de la última generación y no el control de versiones de hace diez años.

Si el cambio está terminado y aceptado por el cliente, entonces se vuelve a guardar la versión final en un directorio del sistema operativo. Si queremos guardar estas dos versiones, entonces podemos usar dos subcarpetas “versión 1” y “versión 2”. Personalmente prefiero usar la fecha, algo como “Versión 2010-06-01”. Así uno no se lía con los números de versiones y queda aún más claro cual es la más reciente.

En fin, guardar proyectos en carpetas simples en lugar de mantenerlos en un control de versiones puede ser una mejor solución para proyectos pequeños y con pocas versiones.

Finalmente quedan todavía dos puntos adicionales a subrayar:

  • Un control de versiones no reemplaza una copia de seguridad. Guardar su trabajo diario en un disco duro alternativo es importante para no perder datos en caso de averías.
  • Aunque el primer fin de un control de versiones es guardar las versiones de sus propios ficheros fuentes, puede convenir guardar bibliotecas externas con las fuentes, ya que una nueva versión de una biblioteca externa no está garantizada de funcionar con una versión antigua del programa. No es un error guardar todas las bibliotecas externas para cada proyecto por separado, aunque serán siempre las mismas bibliotecas. Simplemente piensa qué frustración puede ser sacar un proyecto viejo del armario y que este no compila directamente porque todavía toca buscar todas las bibliotecas por ahí y a saber con qué versión.

Por cierto, nombrar carpetas con fechas es una manera simple de organizar copias de seguridad del trabajo del día.

Referencias

Con tantas herramientas de backup, la gente se olvida muchas veces de la manera más simple de hacer copias de seguridad (si no se olvida directamente de las copias de seguridad por completo): los directorios del sistema operativo. Copias el directorio con todo su contenido, ya tienes una copia de seguridad.

Para tener aún más seguridad conviene guardar las carpetas de copia en otro disco duro o mejor aún en otro ordenador, para que su vida no dependa de la supervivencia del mismo disco que el original.

Yo uso incluso dos carpetas de backup. Uno se llama “Backup” y guarda copias enteras de carpetas. Las suelo numerar de forma secuencial, por ejemplo “Imágenes 1”, “Imágenes 2”, “Imágenes 3”, “Archivos de programas 1”. La fecha de modificación de la carpeta ayuda a saber cuál es la copia más vieja cuando hace falta liberar espacio.

Como no es tan fácil copiar la carpeta de documentos de Windows por tantos ficheros de sistemas que contiene, conviene guardar sus propios ficheros en una subcarpeta de “Mis Documentos” en que sólo tú guardas cosas (y no el ordenador). Para la carpeta “C:\Windows” siempre he preferido usar el sistema de Backup de Microsoft Windows mismo. Es una carpeta delicada y supongo Microsoft sabrá como restaurar datos ahí. El fichero que genera puedes guardar igualmente en la carpeta “Backup”. Si la marcas como comprimida, entonces tienes un dispositivo de backup rápido y comprimido.

Mi otra carpeta de copias se llama “QuickBackup“, donde guardo el trabajo del día o ficheros destinados a la papelera pero en que yo mismo quiero decidir cuando desaparezcan físicamente del disco duro. Las subcarpetas tienen nombres como “2010-06-01”. Es fácil saber de qué día son, no hace falta herramienta adicional para restaurar los ficheros y siempre sabes cuales son las carpetas más viejas a la hora de borrar copias antiguas. Normalmente borro las carpetas tras dos a cuatro meses – un tiempo en que ya no me acuerdo que guardé entonces.

Así, antes de pagar mucho por un sistema de copias de seguridad simplemente usa el disco duro de tu ordenador viejo.

¿Qué es un control de versiones?

Un control de versiones una herramienta para el desarrollo de software que facilita principalmente dos funciones:

  1. Ayuda a que varios programadores pueden trabajar en paralelo.
  2. Permite mantener varias versiones de un mismo programa a la vez. (De ahí “control de versiones”)

Trabajar en paralelo

Si dos programadores realizan cambios en un mismo fichero fuente, entonces sobreescriben los cambios del otro cada vez cuando lo guardan. Incluso si un equipo de trabajo llega a organizarse para que esto no sucede, todavía es probable que todos los “prints”, “ifs”, y demás modificaciones temporales que un programador pueda poner para probar su código molesten a los demás. Si el programa no compila entonces todos los demás están parados hasta que se haya arreglado el error.

Aquí ayuda un control de versiones. Los ficheros “buenos” – es decir una versión que al menos compila – están en un servidor, el “repositorio”. Un programador trabaja sobre una “vista” a estos ficheros (habitualmente una copia local en el ordenador del programador). Si quiere cambiar un fichero, entonces debe “sacarlo del control” (hacer un check-out o desproteger). Mientras tanto los demás programdores siguen viendo la versión original del fichero y no están afectados por las modificaciones de un miembro de equipo.

Cuando el primer programador cree que su versión modificada funciona razonablemente bien, entonces la “sube” (mete, hace un check-in o la protege). Con esto se ha creado una nueva versión, que será la que verá todo el mundo que “actualice su vista”. Un control de versiones no reemplaza a una copia de seguridad, porque no se guardan los cambios en el servidor hasta que el programador lo ordene. Y esto puede durar un mes en ocasiones.

Merge

Un control de versiones sólo permite “subir” un fichero, si es el sucesor de la versión de que fue sacado. Puede suceder que dos programadores sacan sus versiones personales de la misma versión. El primero puede hacer un check-in de sus cambios sin problemas, pero el segundo debe conciliar sus cambios con las modificaciones del otro programador. Un fichero sacado no se actualiza con las versiones que los otros programadores hayan metido, ya que sobreescribirían las modificaciones propias.

La solución es un “merge” (inglés para combinar). Habitualmente se abre una pantalla con las tres versiones afectados: La versión original de donde se partió, la versión a meter y la última versión bajo control. En un caso simple se ha modificado el fichero en puntos diferentes y se pueden simplemente incluir los cambios de la versión más reciente en la versión a meter. Dos cambios en una misma línea de código causan un “conflicto” que el programador debe resolver a su criterio y con la ayuda del otro programador. Muchas veces un control de versiones puede combinar versiones sin conflictos de forma automática. No es posible hacer un merge en ficheros binarios.

Mantener varias versiones

En muchos programas de uso común es habitual mantener varias versiones. Por ejemplo, no todo el mundo está dispuesto a instalar un nuevo sistema operativo cuando Microsoft publique una nueva versión de Windows. Así Microsoft debe mantener varias versiones de Microsoft Windows al mismo tiempo que está desarrollando la próxima generación.

¿Qué significa varias versiones? Cada vez cuando un programador sube sus cambios, se crea una nueva versión que el sistema enumera con un número secuencial. Podemos decidir que alguna de estas versiones, digamos la versión 3124, será destinada a ser una “release” oficial. Entonces se “etiqueta”, por ejemplo como “Windows 8 alpha” y se crea una nueva “rama” (branch en inglés). La rama principal (“trunk” en inglés) es la en que los programadores hagan el desarrollo nuevo. La rama “Windows 8 alpha” existe en paralelo y sirve para corregir los errores que todavía pueda tener. En esta versión interesa más llegar a una versión “estable”, un “release”, que añadir un nuevo desarrollo.

Lógicamente, todos los errores que se encuentran en la versión “Windows 8 alpha” habrá que corregir también en la rama de desarrollo principal. También puede suceder que alguna funcionalidad nueva de la rama de desarrollo entra en la rama de la versión “release”. En general, los programadores tienen que modificar varias versiones y el control de versiones les permite determinar cuales.

Como es imaginable, una rama de una release puede bifurcarse también. Una sigue con las correcciones de la versión (oficial) 8.0, la otra está destinada a incluir mejoras para la release 8.1. En el momento que una versión ya no incluirá nuevas funcionalidades se “congela”. Cuando ya no se trabaja sobre ella ya no está “soportada”.

Pequeña lista comentada de control de versiones

Hasta algunos años, la comunidad de código abierto ha usado con mucho gusto el CVS (Concurrent Versions System). Ahora se usa más el Subversion, que ofrece un cliente integrado en el explorador de Windows que se llama TurtoiseSVN. Es todo gratis y una buena solución para la mayoría de los proyectos.

Cuando gratis no es un requisito puede convenir usar IBM® Rational® ClearCase®, un programa completo que permite un uso por línea de comando y por interfaz gráfico. Microsoft Visual SourceSafe es un extra con las versiones de empresa de Visual Studio, pero que a veces da impresión de ser ni visual ni seguro. La ventaja que tiene es que se integra bien con el Visual Studio.

Quien piensa en grade debe tener en cuenta que eligir una herramienta de control de versiones es una decisión estratégica de la empresa. Una base de datos es lo más difícil de actualizar en un programa y un control de versiones no es otra cosa que una base de datos donde los datos son ficheros. Es bastante probable que una empresa todavía usa el control de versiones de hoy en diez años.

En cada proyecto existe un flujo de trabajo, en se recurren de forma secuencial varias etapas.

  1. Se genera una idea general de que debe hacer el proyecto. Por ejemplo un programa que controla los movimientos de trenes en una estación.
  2. Los ingenieros de sistema elaboran con los clientes un cuaderno de carga y traducen los requisitos a un diseño. Por ejemplo:  El programa tiene una ventana en que se puede editar el horario del tren. Tiene un botón “Aceptar” que copia los datos en la ventana a la base de datos.
  3. Los programadores escriben un código que hace esto.
  4. Los ingenieros de prueba comparan el comportamiento del programa con los requisitos en el cuaderno de carga

¿Esto no suene totalmente lógico? Pensar qué quieres, cómo lo quieres, hacerlo y comprobar si lo has hecho bien. Lógicamente es un ideal que en una empresa de alta tecnología no se puede conseguir siempre. Por lo tanto, el ciclo de desarrollo suele tener típicamente más bien el siguiente estilo.

  1. El director general de los tuyos y de los suyos firman un contrato, donde aparece por primera vez una fecha de entrega.
  2. Los ingenieros de sistema comienzan a ingeniarse un sistema y avanzan a buen ritmo.
  3. El jefe de los ingenieros de sistema se da cuenta que el buen ritmo haría duplicar el tiempo previsto para esta fase y pide que se diseñen los componentes en dos en lugar de cuatro semanas.
  4. Como los ingenieros de sistema no llegan, los programadores empiezan a programar aunque todavía no está de todo claro qué.
  5. Los programadores avanzan a buen ritmo.
  6. A la medida que los ingenieros de sistema completan el diseño del programa, los programadores deben modificar el código.
  7. Los ingenieros de prueba comienzan a probar el programa que a veces falla porque las partes en cuestión aún no están programadas.
  8. Entre fijar los errores reportados por los ingeniero de prueba y modificar el diseño del programa hay tímidos intentos de adaptar el programa para hacerlo más legible, orientado a objetos, modular y tal. Por alguna coincidencia hay de repente dos días enteros para esto porque el programa ya contiene todo para la primera entrega parcial al cliente.
  9. El cliente está contento porque ve que están todas las ventanas aunque los botones no funcionan. Los ingenieros de sistema sugieren un cambio propuesto por los programadores de reducir el número de
    los botones “Aceptar” a uno por ventana.
  10. Los programadores lo cambian.
  11. Mientras añaden componentes adicionales a la funcionalidad, el cliente se muestra preocupado por el elevado número de errores detectados por los ingenieros de prueba. El jefe del programa promete reducirlo.
  12. Como el tiempo entre arreglar errores y programar nuevas partes con más errores se hace corto, el jefe del grupo prefiere aumentar la rapidez. Lo que se podría dividir en dos ficheros también cabe en uno, además a estas alturas del proyecto ya no conviene agrupar los ficheros en directorios por tener una mejor modularidad.
  13. El cliente se da cuenta que no se puede configurar la aplicación. Pide editores para que los parámetros fijos sean variables inicializadas con un fichero de texto.
  14. Los programadores empiezan a reescribir su código para que todos los arrays sean de un tamaño variable.
  15. El jefe del programa se muestra preocupado, porque que fallan partes del código que funcionaban antes.
  16. Los ingenieros de sistema adaptan su documentación de diseño a lo que realmente hay programado.
  17. El programa se cuelga tres veces en una prueba con el cliente. Esto tiene máxima prioridad y justifica que al final, sí, se dividen los ficheros en varios directorios.
  18. Aún falta un 20% de la funcionalidad. La lista de errores ha crecido porque todos los programadores estaban ocupados por los fallos fatales de la semana pasada. Al mismo tiempo, se ponen por lo menos tres errores por anomalía reportada para que el número de errores parezca más pequeño.
  19. Un programador detecta que la ventana de configuración debe tener opciones que son técnicamente imposibles de realizar. Después que el programador descubra como se podría hacer algo similar, el ingeniero de sistema propone que el programador le diga como lo haya programado para que pueda adaptar el documento de diseño.
  20. El programa se cuelga sin más razón aparente cuatro días antes de la prueba final. Las revisiones de los programadores durante el fin de semana fallan por la documentación incompleta de bibliotecas externas. El cliente no acepta el programa a pruebas.
  21. Tras haber codificado toda la funcionalidad, el cliente quiere que todos los mensajes de textos sean leídos desde un fichero. Realmente ya lo quería desde el principio, pero como esto no añade funcionalidad, nunca se hizo.
  22. Tres programadores se quedan con los errores no resolubles. Uno de ellos tiene también la tarea de inventarse los comentarios para que parezca que al menos un 30% de líneas sean comentarios.
  23. Supuestamente, el cliente usará el proyecto y no se puede excluir que también será documentado.

¿Qué conclusiones podemos sacar? Pues, la primera es ciertamente que hagas un repaso a tus ideales juveniles pero sin deprimirte. Aunque parece imposible de cambiar el mundo entero, sí, es posible que al menos tú hagas lo mejor posible.

Por ejemplo, el cambio que podrías enfocar desde ahora es dejar de quejarte de que la imprevisión e la improvisación son la regla (a pesar de lo que diga tu jefe), sino que se planifica en tiempo real. Suene muy bien y es una pieza para obtener la actitud adecuada para que algún día tú serás el jefe.

Te deseo mucha suerte.

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

Únete a otros 51 seguidores

Archivos

junio 2018
L M X J V S D
« Abr    
 123
45678910
11121314151617
18192021222324
252627282930  
Anuncios