RESUMEN
La gestión documental se ha convertido en una necesidad para las organizaciones
donde se genere gran cantidad de información e implica el uso de diversas
herramientas o métodos de proceder que permiten un mejor funcionamiento de la
organización.
Un proyecto de software es una organización donde se gestiona un cúmulo de
documentos. Unos forman parte del producto de software final y otros son
necesarios para el trabajo de los desarrolladores en el propio desarrollo del
software.
En función de esto, se ve la necesidad de definir un rol encargado de gestionar
la documentación en el proyecto de software. A este rol se le conoce como rol
documentador.
En el presente trabajo se presenta una propuesta de un conjunto de actividades,
artefactos y responsabilidades que debe desempeñar el rol documentador en el
proceso de desarrollo del software.
Palabras claves: Documentación, Documentador, Gestión documental
Abstract
Document management has become into a necessity for the organizations that
produce a lot of information, and implicates the use of many tools or practices
that allow a better performance of the organization.
A software project is an organization that manages a great quantity of documents.
Some of them are part of the final software product and the others are necessary
for the developments into the software development.
That is the reason for which it is a necessity to define a role that manages the
documentation into the software project. That role is known as technical writer.
This work presents a proposal of a set of activities, artifact and
responsibilities that a technical writer must play into the software development
process.
Keywords: Documentation, document management, technical writer
ÍNDICE
Introducción
Desarrollo
Flujo de trabajo del rol Documentador
Responsabilidades
Flujo de trabajo del rol de documentador
Artefactos del rol de documentador
Actividades del rol de documentador
Relación con otros roles
Herramientas de apoyo
Conclusiones
Referencias bibliográficas
Datos de los autores
INTRODUCCIÓN
La gestión documental[1] no es un término nuevo pero se perfila como un tema
mundialmente tratado debido a la amplia cobertura de la información en la era
actual; y adquiere mayor importancia estratégica en el desarrollo de una
organización.
Hoy en día es un hecho que la informática y las comunicaciones rigen los
sectores más importantes de la economía a nivel mundial y los procesos de las
organizaciones.
En ese sentido, el desarrollo de software se encuentra en el centro de todas las
grandes transformaciones; sobre todo si se considera que grandes temas del
momento como lo son la economía digital, la evolución de las empresas y la
administración del conocimiento, se resuelven con software. (PEÑALOZA 2002)
El software se ha convertido en el elemento clave de la evolución de los
sistemas y productos informáticos. En los pasados 50 años, el software ha pasado
de ser una resolución de problemas especializados y una herramienta de análisis
de información, a ser una industria por sí misma. (PRESSMAN 2002) La Industria
del Software es la industria que involucra la investigación, desarrollo,
comercialización y distribución de software.
En la Industria de Software, la gestión documental consiste en el uso de
tecnologías y procedimientos que permiten el almacenamiento organizado, el
control de versiones y el acceso a la información generada en el seno de un
proyecto de software por el personal de desarrollo, clientes e involucrados.
Pretende el tratamiento integral, consistente y fiable de los documentos y la
información que se genera en las transacciones y procesos de negocio.
La documentación proporciona el fundamento para un buen desarrollo y, lo que es
más importante, proporciona guías para la tarea de mantenimiento del software. (PRESSMAN
2002)
Pero, ¿quién se encarga de gestionar la documentación dentro de un proyecto de
desarrollo de software? Este rol dentro del proyecto lo juega el documentador.
De manera general existe el mito de que el documentador sólo es responsable de
escribir texto aceptado, legible, accesible y útil para su audiencia; pero este
rol, no sólo se encarga de suministrar material al usuario final. Es
responsable, además, de que ese material tenga la calidad requerida y pueda ser
fácil de asimilar incluso por personas no conocedoras del tema. Esto implica
definir estilos y formatos de redacción.
Para que haya vigencia del trabajo que se desempeña y queden plasmadas tareas y
acuerdos para el desarrollo del proyecto se redactan actas durante las
reuniones. Dichas actas son levantadas por el documentador.
En el transcurso del proyecto se genera documentación que es usada por el equipo
de trabajo y que es responsabilidad también del documentador. Las decisiones de
las herramientas a utilizar o de estrategias a seguir para la gestión documental
recaen, también, sobre este rol.
Así, el documentador realiza disímiles actividades en función de mejorar la
calidad en el tratamiento de la documentación y en vísperas de lograr un mejor
desarrollo en el proyecto de software.
DESARROLLO
Flujo de trabajo del rol Documentador
En los actuales procesos de desarrollo de software, se gestiona un cúmulo de
información, ya sea por problemas de legibilidad del producto, por dejar
constancia de las actividades que se lleven a cabo o por facilitar y proveer
conocimientos lo más asequible posibles al equipo de desarrollo y a quienes
operen el sistema.
Las actividades que se puedan realizar en aras de la gestión documental
corresponde desempeñarlas al rol documentador.
A continuación se define un flujo de trabajo para el rol documentador a raíz del
propio desarrollo de un proyecto de software y con el fin de lograr la calidad
requerida en la obtención, procesamiento, almacenamiento y distribución de la
información, para así obtener de ella el máximo rendimiento personal de cada
integrante del equipo de desarrollo.
Responsabilidades
La principal responsabilidad del rol de documentador es mantener la información
generada durante el proceso de desarrollo con un adecuado procesamiento que
permita la calidad en el mantenimiento de la misma. Existen otras
responsabilidades ya no tan elementales, pero que complementan la eficiencia y
rendimiento de las tareas del rol documentador, entre ellas están:
Organizar y garantizar el almacenamiento y recuperación de la documentación de
los procesos y productos más recientes durante el desarrollo, manteniendo así la
información al día.
Mantener la consistencia en la apariencia y estructura de los documentos,
facilitando su almacenamiento, recuperación e intercambio, no permitiendo el
almacenamiento de documentos con formatos diferentes al establecido.
Generar plantillas que permitan una adecuada estructura y uniformidad en los
documentos que lo requieran.
Elaborar, almacenar y permitir la recuperación de la documentación que se genera
como parte de la gestión del proyecto.
Construir documentación de cara al usuario que contempla los aspectos que son de
utilidad para los usuarios finales del sistema y proveer una adecuada
capacitación.
Flujo de trabajo del rol de documentador
El flujo de trabajo del rol documentador contiene actividades que tienen un
propósito específico y están asociadas a un conjunto de artefactos que se
requieren para realizar las actividades y otro conjunto que son productos de
estas, a los que se les llama artefactos de entrada[2] o de salida[3]. (Ver
figura 1)
Figura SEQ Figure \* ARABIC 1 Actividades y artefactos del rol de documentador.
Artefactos del rol de documentador
Nombre: Estructura del repositorio
Objetivo: Definir la estructura de carpetas y archivos en el repositorio de
información.
Descripción: En este artefacto se describe la organización que tendrá la
documentación en el repositorio a partir de la estructura de los diferentes
niveles de carpetas que identifican cada una de las áreas del proyecto,
detallando los criterios que se siguen para agrupar la documentación.
Ocurrencia: Este artefacto se genera en la fase de inicio del proyecto, como
parte de las actividades del rol de documentador y puede refinarse en etapas
posteriores según las necesidades que surjan dentro del propio proceso de
desarrollo y se utiliza como entrada en la actividad de definir los perfiles de
acceso al repositorio, sirviendo de base para identificar dónde y con qué
permisos entran cada uno de los roles del proyecto en la estructura creada.
Roles involucrados:
Nombre: Perfiles de acceso
Objetivo: Definir perfiles de acceso y políticas de seguridad.
Descripción: Se describen los perfiles de acceso y las políticas que se
siguieron para establecer un sistema de seguridad en el acceso al repositorio.
Dichos perfiles cuentan con permisos determinados de seguridad a todos los
archivos que conforman el proyecto con la posibilidad de visualizarlos,
crearlos, modificarlos o eliminarlos.
Ocurrencia: Este artefacto se genera en la fase de inicio, como parte de las
actividades del rol de documentador y puede actualizarse en etapas posteriores,
cuando cambios en la estructura del repositorio y/o cambios en las
funcionalidades de los roles dentro del proyecto lo sugieran.
Roles involucrados: Gestor de configuración
Nombre: Estándares de la documentación
Objetivo: Proponer estándares para la documentación del proyecto.
Descripción: Se hace una propuesta por parte del equipo de documentación de
estándares para la documentación del proyecto, ya sea digital o en formato duro
a partir de estándares ya definidos e internacionalmente reconocidos.
Ocurrencia: Este artefacto se crea en la fase de inicio, como parte de las
actividades del rol de documentador.
Roles involucrados: Revisor técnico
Nombre: Plantillas
Objetivo: Estructurar los documentos que se generen en el seno del proyecto.
Descripción: Este artefacto permite realizar una documentación uniformemente
estructurada por parte del equipo de desarrollo. Dentro de este artefacto se
identifican las plantillas de documentación del código y las plantillas para los
documentos que definen el flujo de trabajo de cada rol del proyecto.
Ocurrencia: Este artefacto se va generando con el propio proceso de desarrollo,
siempre y cuando el tipo de documentación que se genere lo requiera, siendo esto
parte de las actividades del equipo de documentación.
Roles involucrados:
Nombre: Actas de reuniones
Objetivos: Almacenar las ideas expuestas en las reuniones que se lleven a cabo
en el seno del proyecto.
Descripción: Este artefacto recoge todo lo que acontece en las reuniones de
revisiones del proyecto, donde se registran una serie de informaciones a raíz de
la revisión, permitiendo al equipo de desarrollo la búsqueda de los temas
tratados en una fecha determinada una vez que las actas hayan sido almacenadas
en el repositorio de documentación.
Ocurrencia: Este artefacto se realiza durante las diferentes etapas del proceso
de desarrollo, como parte de las actividades del equipo de documentación.
Roles involucrados:
Nombre: Ayuda del sistema[4]
Objetivo: Proporcionar un sistema de ayuda online para uso de los usuarios
finales.
Descripción: Este artefacto es un tipo de sistema de apoyo en línea que
proporciona una información breve y concisa para resolver un problema puntual
durante el trabajo del usuario.
Ocurrencia: Este artefacto se genera en la fase de elaboración y se va refinando
en las siguientes fases de forma tal que el sistema de ayuda que se entrega al
cliente coincida con la versión final de la aplicación.
Roles involucrados:
Nombre: Manuales de cara al usuario
Objetivo: Proporcionar documentos que faciliten el correcto entendimiento del
sistema por parte de los usuarios finales.
Descripción: Este artefacto brinda la posibilidad de mostrar todas las
funcionalidades del sistema dando una explicación de cada una de las partes que
lo componen y de su forma de uso, lo cual permite operar el sistema
correctamente y administrar los errores que puedan aparecer durante su
ejecución.
Ocurrencia: Los primeros pasos de este artefacto comienzan durante la fase de
elaboración, cuando las funcionalidades del sistema comienzan a evolucionar.
Este documento continúa refinándose en las fases de construcción y transición,
en paralelo con el propio desarrollo del sistema, siendo en todo momento una de
las actividades del rol de documentador.
Roles involucrados:
Actividades del rol de documentador
Nombre: Diseñar y construir un repositorio de información.
Objetivo: Crear un repositorio central.
Descripción: Con el diseño y construcción del repositorio de información se
obtiene una estructura global del mismo a partir de identificar las necesidades
de cada una de las partes implicadas, permitiendo almacenar, recuperar y
mantener la documentación de las distintas áreas involucradas en el proyecto y
tener accesible y organizada la última versión de todos los documentos generados
durante el proceso de desarrollo.
Roles involucrados: Líder de proyecto, Arquitecto principal, Gestor de
configuración
Artefactos de entrada:
Artefactos de salida: Estructura del repositorio
Nombre: Definir perfiles de acceso al repositorio.
Objetivo: Garantizar la seguridad de la información almacenada en el
repositorio.
Descripción: Una vez creado el repositorio y garantizando la seguridad de la
información, se evita que cualquier persona pueda alterar algún documento si no
tiene permisos para ello. Los perfiles de acceso a una persona se asignan o
restringen en correspondencia con las funciones que ejerza como rol dentro del
proyecto y en correspondencia con el área de trabajo a la que pertenezca; puede
crear, modificar, visualizar o eliminar información.
Roles involucrados: Responsables de áreas, Gestor de configuración
Artefacto de entrada: Estructura del repositorio
Artefacto de salida: Perfiles de acceso
Nombre: Definir estándares para la documentación.
Objetivo: Establecer estándares que rijan el proceso de documentación.
Descripción: Al definir los estándares que rigen la documentación a partir del
estudio de normas y estándares ya definidos a nivel mundial y un análisis de las
características que particularizan el proyecto; se facilita su almacenamiento,
recuperación e intercambio y se presenta de forma organizada y bien
estructurada; alcanzando homogeneidad en la apariencia de la documentación.
Roles involucrados: Revisor técnico
Artefactos de entrada: Norma NC-ISO-IEC 12119, Estándar IEEE 1063TM
Artefactos de salida: Estándares de la documentación
Nombre: Elaborar plantillas.
Objetivo: Obtener plantillas para la estructuración de la documentación.
Descripción: Permite que documentos como el flujo de trabajo de cada rol y la
documentación del código se presenten de forma uniforme, guiando a cada
interesado en los aspectos que le puedan ser útil del documento.
Roles involucrados: Desarrolladores, Responsables de las áreas del proyecto
Artefactos de entrada:
Artefactos de salida: Plantillas
Nombre: Elaborar actas de reuniones.
Objetivo: Archivar las ideas expuestas y acuerdos tomados en las reuniones del
proyecto.
Descripción: Al elaborar las actas debe quedar por escrito las ideas que fueron
expuestas en las reuniones y que sirven de fundamento al trabajo que se
desarrolla en el proyecto. No basta con elaborarlas, también es necesario su
almacenamiento y recuperación. Al término del proyecto, el repositorio contendrá
toda la información histórica del mismo recogida en las actas.
Roles involucrados:
Artefactos de entrada:
Artefacto de salida: Actas de reuniones
Nombre: Crear Sistema de Ayuda.
Objetivo: Elaborar sistemas de ayuda online.
Descripción: Esta actividad tiene como propósito que el manejo de la aplicación
tenga un soporte dinámico y contextual que ayude a su utilización, integrando
todas las técnicas necesarias para solucionar cualquier tipo de necesidad del
usuario.
Roles involucrados:
Artefacto de entrada: Documentación de cara al usuario
Artefacto de salida: Ayuda del sistema
Nombre: Crear documentación de cara al usuario.
Objetivo: Elaborar documentación de cara al usuario.
Descripción: Teniendo en cuenta los estándares propuestos para la documentación
de cara al usuario y a partir del prototipo de interfaz de usuario, se crean
documentos que explican detalladamente las funcionalidades del sistema con las
cuales interactúa el mismo.
Roles involucrados: Analistas, Diseñadores gráficos
Artefacto de entrada: Prototipo interfaz de usuario
Artefacto de salida: Manuales de cara al usuario.
Nombre: Capacitar a usuarios finales.
Objetivo: Entrenar a usuarios finales en cuanto a uso y funcionalidad del
sistema.
Descripción: Teniendo en cuenta los materiales de soporte al usuario final del
sistema, se asiste a los usuarios en forma sistemática durante un tiempo para
asegurar la fluidez de las operaciones, logrando que los mismos tengan el
dominio necesario de las cosas básicas de tecnologías y procesos que se emplean
para su operación de manera eficiente y segura.
Roles involucrados:
Artefacto de entrada: Materiales de soporte al usuario final del sistema
Artefacto de salida:
Relación con otros roles
El rol de documentador sirve como medio de comunicación entre los miembros de
los diferentes roles del proyecto. El documentador genera documentos y se
responsabiliza con la gestión de toda la documentación residente en el
repositorio, estableciendo políticas de seguridad para el acceso a la
información del repositorio y velando que cumplan con el estándar de
documentación vigente en ese momento.
Mantiene una estrecha relación con los analistas de sistema y diseñadores
gráficos puesto que de ellos recibe descripciones del prototipo al efectuarse el
levantamiento de requisitos en la fase de inicio y las pantallas que son
generadas a partir de estas descripciones respectivamente, de forma tal que la
realización de los manuales comiencen durante la fase de elaboración, cuando las
funcionalidades del sistema comienzan a evolucionar. Estos documentos continúan
refinándose en las fases de construcción y transición, en paralelo con el propio
desarrollo del sistema.
Herramientas de apoyo
El documentador requiere herramientas para la elaboración de documentos
(minutas, documentos de acuerdos, manuales, Sistema de Ayuda) y herramientas de
apoyo para la elaboración y administración del repositorio de documentos. Dentro
del primer conjunto de herramientas se encuentran las siguientes:
Editor de texto Microsoft Word, que permite elaborar documentos fácilmente.
Sistema de Gestión Documental, que proporcionan un repositorio de información.
Herramienta para elaborar un Sistema de Ayuda.
Por otro lado, las herramientas de apoyo para la elaboración y administración
del repositorio de documentos deben proveer el acceso a los documentos. Estas
herramientas se definen en posteriores momentos de la investigación.
CONCLUSIONES
Como se ha definido a lo largo de la investigación, el rol de documentador
realiza actividades y genera artefactos apreciables por el equipo de desarrollo
del proyecto y, en gran medida, por el usuario final a quien están dirigidos el
mayor porcentaje de los esfuerzos y el proceder de este rol.
De igual manera, existen aspectos que no pueden ser ignorados debido a que
guardan una estrecha relación con el rol documentador y que, en vísperas de
construir software con la calidad exigida por la sociedad actual, juegan un
papel fundamental en el desarrollo de los productos que se generan. Por eso
constituye un camino exitoso el empleo de herramientas que soporten la gestión
documental, incorporar al documentador en la producción y mantenimiento del
software así como trazar responsabilidades que rigen las actividades concretas
que desempeña el rol documentador.
REFERENCIAS
[1] También denominada gestión de documentos o gestión de la documentación.
[2] Los artefactos de entrada son productos tangibles que son usados en la
realización de las actividades del proceso de desarrollo del software.
[3] Los artefactos de salida son productos tangibles que pueden ser modificados
o creados en la realización de las actividades del proceso de desarrollo del
software.
[4] El término ayuda del sistema se refiere a un Sistema de Ayuda para el
usuario final.
REFERENCIAS BIBLIOGRÁFICAS
BJÖRK, B.-C. Document management - a key technology for the construction
industry. Information and Communications Technology (ICT) in the Practice of
Building and Civil Engineering, Helsinki, Finland, Association of Finnish Civil
Engineers, 2001. 35-43 p. ISBN 951-758-417-2
JACOBSON, I.; G. BOOCH, et al. El Proceso Unificado de Desarrollo de Software.
Primera Edición. Madrid, 2000. 464 p. ISBN 84-7829-036-2
PEÑALOZA, M. La industria del software, una oportunidad para México Entérate,
2002.
PRESSMAN, R. S. Ingeniería del Software: Un enfoque práctico. Quinta Edición.
2002. p.
RUP. Rational Unified Process Version 2003.06.00.65, Rational Software
Corporation, 2003.
AUTORES
Ing. Yanay Viera Lorenzo
Ingeniero en Ciencias Informáticas
Profesor Universidad de las Ciencias Informáticas
yvieral@uci.cu
Ing. Daimara Mustelier Sanchidrian
Ingeniero en Ciencias Informáticas
Profesor Universidad de las Ciencias Informáticas
dmustelier@uci.cu
Coautora:
Ing. Lizandra Arza Pérez
Mayo, 2008
