Plan de Documentación

Un Plan de Documentación describe los medios que se pondrán a disposición del esfuerzo de documentación del proyecto de desarrollo. Entre otros medios, podemos imaginarnos recursos tales como plantillas, redactores técnicos, guías de estilo, procesadores de texto, etc.

Es sin duda un plan simple, en el sentido en que puede considerarse completo con relativamente poca extensión. Sin embargo es también un típico plan dejado solo para las organizaciones más maduras, ya que muchos simplemente dejan a su esfuerzo de documentación sin planificación alguna.

La creación de documentos completos y útiles no es un arte; es una práctica esencial de la ingeniería y como tal, debe ser vista como algo rutinario, sistematizado con herramientas y en la medida de lo posible, agilizado.

En el espíritu de la agilidad, lo mejor es planificar medios para documentar los aspectos técnicos del proyecto en herramientas de modelado UML[1], prefiriendo estas a los reportes tradicionales que obligan a un mayor trabajo de edición. También es interesante explorar la posibilidad de utilizar técnicas alternativas de documentación, como las Wikis que permitan crear y utilizar la documentación en formas más rápidas.

Otro aspecto a documentar aquí, es el formato de archivo o formatos, que se van a utilizar. Quizás una organización pueda preferir tener sus documentos en formato ODT[2] de OpenOffice, o bien el formato RTF, o quizás en HTML; entre otras muchas posibilidades. La elección puede facilitar mucho el trabajo y sin duda tendremos problemas si hay alguien que no la respete.

No es ilógico tampoco, planificar aquí, que los documentos estarán disponibles en determinada dirección o bien, que tendrán copias actualizadas en formato PDF. La política de propiedad de los documentos así como el responsable de centralizar la publicación de estos, son también aspectos interesantes dignos de contar con una palabra o dos.

Los planes de documentación también guardan relación con el Plan de Mejoramiento del Proceso, ya que al planificar la creación de plantillas, o la actualización de un repositorio de documentos, es posible identificar elementos reutilizables que redunden en una mejora del método de desarrollo con miras a futuros desarrollos.

Por ultimo, he de indicar, que por lo breve de su extensión, es posible que este plan lo mantengamos como parte del documento llamado Plan de Desarrollo de Software, con lo que en realidad podríamos no tener un documento por separado con esta información.

Documento del Proceso (II)

Según las practicas comunes en cada lugar u organización, los elementos comunes de los documentos vienen dispuestos en distintos lugares del mismo. Un ejemplo de esto es el Indice de Contenido, el cual suele colocarse de primero o en las primeras páginas del documento en Venezuela y otros países de habla española, en tanto que en USA muchas veces es colocado de ultimo.

Diferencias como la anterior no nos deben llamar a la admiración ni constituire en un problema. De todos modos, cada artefacto del proceso, e incluso el proceso mismo de cada organización debe ser adaptado a sus propias necesidades y costumbres, por lo que tener el indice en un lugar distinto al sugerido en metodologías como RUP es algo muy natural.

Por otro lado, si bien la disposición de los elementos comunes puede variar, debería tenerlos en algún sitio bien definido de sus documentos, ya que recogen información útil sobre los pasos del proceso.

Finalmente, una lista parcial de elementos para que los tenga en consideración:

• Identificación del documento: Título, Proyecto y Versión.
• Identificación del autor: Nombre e información de contacto.
• Identificación de quien aprueba, en caso de requerirse una aprobación.
• Historial de versiones del documento.
• Glosario de términos utilizados.
• Glosario visual de los iconos utilizados.
• Alcance del documento, esto es, identificar que parte del proceso o del sistema que se cubre en el documento. Por ejemplo Arquitectura del Sistema: Módulo de Atención al Cliente.
• Artefactos tomados como entrada, indicando nombre y versión.
• Artefactos generados como derivados, indicando nombre.
• Anexos.
• Indice de Contenido.
• Indice de Figuras.
• Indice de Tablas.

De la lista anterior, tome lo que considere que se justifica para su organización. Es importante que mantenga el alcance del documento, así como la relación de artefactos en entrada y salida, ya que esta información le ayuda más adelante con las trazas de requisitos.

Coloque los nombres de las secciones y escriba pequeñas secciones de introducción a cada sección. Añada además las notas e indicaciones para los futuros usuarios de su plantilla. Recuerde que estas plantillas serán llenadas por seres humanos, por lo que las indicaciones en cuanto a estructura, forma y contenido que pueda ir planificando desde ahora le harán la vida más sencilla en un futuro. Todo esto será de utilidad cuando intente en realidad hacer su trabajo con ayuda de la documentación que produzca.

Documento del Proceso

A diferencia del Documento en Blanco, este nuevo artefacto posee una estructura visible. No solo se han utilizado aquí los margenes y estilos definidos en la plantilla de base -la de Documento en Blanco, tengamos presente- sino que se han añadido elementos que serán comunes a todos nuestros documentos a lo largo y ancho de nuestra organización.

Sugiero que las plantillas sean vistas como una jerarquía de clases de documentos. De esta forma, Documento en Blanco seria el objeto raíz dependiente de plataforma y la plantilla Documento del Proceso sería nuestra raíz independiente de la plataforma pero definida enteramente para las necesidades del proceso.

Me explico: la plantilla Documento en Blanco tendrá opciones propias del editor de textos que utilicemos, fijadas de forma tal que todos los documentos que se escribamos sobre está tengan un aspecto uniforme. Por tener en su diseño consideraciones del procesador de textos, le llamo a esta plantilla «dependiente de la plataforma».

Por otra parte, la plantilla de Documento del Proceso es diseñada pensando exclusivamente en la organización común de los documentos a desarrollar en la organización. Ahora las opciones exactas de formato no son nuestro problema. En su lugar nuestro objetivo es enteramente la estructura del documento y la forma en que se utilizará. Esto es, la plantilla es «dependiente del proceso».

Según cuales sean nuestras influencias metodológicas, la estructura de este documento puede cambiar. Sin embargo parece razonable que deberá incluir información de identificación suficiente, quizás un historial, y anexos tales como un glosario.

Fije usted toda esta estructura en la plantilla. De ser necesario coloque pequeños comentarios sobre el propósito de cada sección. A estas indicaciones las hemos de colorear o adornar de forma tal que nadie dude que son comentarios para el redactor de documentos, y que por tanto no deben estar presentes en ningún documento entregado.

Suerte en este nuevo artefacto, a partir de aquí los documentos comenzarán a tener un estructura que refleje nuestra manera de trabajar, así que nos tendremos que poner un poco más formales y sugerir organizaciones precisadas en mayor detalle.

Estaremos en contacto.

Documento en Blanco

El joven Johannes se levantó aquel día como todos los días. Con la obligación de ir al trabajo, pero con un peso del alma tan grande, que a duras penas pudo bajar a la cocina a tomar el desayuno.

Su madre le advirtió «come toda tu comida, o las brujas se la llevarán» broma con que siempre le animaba a comer antes de ir a lo que él imaginaba como un horrible trabajo: un centro de copiado de libros. Ahí la labor era pesada y solo la tradición familiar junto a la necesidad de comer, le lograban convencer de ir.

Las responsabilidades de Johannes incluían el tallado de los tipos, pequeñas fichas con la forma de las letras. También se encargaba, cuando su tío el jefe estaba de buen humor, de montar las páginas para su impresión. «Ojalá me permita imprimir hoy» era un pensamiento cotidiano pero que pocas veces se lograba convertir en realidad. Solo los talladores más experimentados podían recibir la confianza suficiente como para arriesgar todo ese precioso trabajo de crear los tipos en la impresión de una hoja de texto. Corria el siglo XV y los libros eran cosa muy delicada.

Así Johannes dedico la mayor parte de su vida a una labor pesada de la que no gustaba. Su sueño fue siempre lograr una forma simple de hacer su trabajo. No podía dedicarse a nada más, así que siguió su instinto e inventiva y termino dando al mundo un objeto de lo más transcendental: la imprenta.

Johannes Gutenberg diseño la imprenta de tipos móviles luego de años de esfuerzo y desarrollo. Todo lo que invirtió en ella le pareció poca cosa, al lado del esfuerzo extraordinario que demandaba el copiado de un libro en sus días.

Cada letra tallada por separado, cada página compuesta a mano, cada folio impreso con cuidado y esmero, y sin embargo todo ese esfuerzo se perdía en poco tiempo dada la fragilidad de los tipos utilizados. La gran novedad de la imprenta no era la técnica en si misma, sino la posibilidad de agilizar el trabajo al simplificar la creación de las letras y la composición de las páginas. Gutenberg utilizo metal para los tipos y pequeños moldes que le permitían crear todas las letras que quisiera con un poco menos de trabajo manual.

Es admirable lo mucho que ha avanzado la tecnología. Hoy en día generamos documentos en pocos minutos, dedicando poca atención a toda la infraestructura que es necesaria para lograr tener una hoja de papel con nuestro pensamiento plasmado en ella.

Quizás las opciones de formato de un procesador de texto moderno no sean tan difíciles de usar como una imprenta de los tiempos de Gutenberg, pero es una irresponsabilidad el pensar que solo por esa facilidad nadie debe ocuparse de los detalles detrás de cada documento.

Es mi tesis aquí, que incluso una humilde hoja en blanco -con sus opciones de margenes, estilos de edición predeterminados, cabezas y pies de página- debe ser objeto de cuidadoso diseño.

No solo para respetar la memoria del joven Johannes y de todas esas comidas que las brujas no se comieron, sino para lograr también, que nuestros documentos tengan un aspecto uniforme y que a lo largo del tiempo, sea más fácil el leerlos.

Recuerde: los procesadores de palabras modernos tienen muchas opciones de formato, no querrá que sus proyectos tengan aspectos diferentes para sus documentos ni mucho menos, que esto pase dentro de un mismo desarrollo.

Así que vaya ahora mismo, y comience a definir como es para su organización, un documento en blanco.