"La documentación de un proyecto es una parte esencial de las actividades que se deben realizar para el correcto desarrollo, implementación y mantenimiento del mismo."
¿Qué documentación debe tener el sistema?
Una de las primeras cuestiones que debe hacer un documentador es conocer el área, tareas que estarán bajo su responsabilidad y las particularidades del proyecto.
¿Qué documentación debe tener el sistema?
Una de las primeras cuestiones que debe hacer un documentador es conocer el área, tareas que estarán bajo su responsabilidad y las particularidades del proyecto.
La siguiente definición de wikipedia nos presenta un vistazo a lo que el Documentador de sistemas se va a enfrentar:
"En sentido restringido, la documentación como ciencia documental se podría definir (a grandes rasgos) como la ciencia del procesamiento de la información, que proporciona información sobre algo con un fin determinado, de ámbito multidisciplinar o interdisciplinar.Siguiendo a Fuentes y Pujol se puede señalar a la Documentación como una ciencia auxiliar e instrumental. También es una ciencia en si misma y una de las finalidades primordiales de la Documentación es informar.1A falta de un consenso, hay diversos autores, como Juan Ros García o José López Yepes, que la consideran una ciencia (documental), a la vez que una disciplina, no sólo una técnica. También pueden considerarse, en sentido general, las ciencias de la documentación y la documentación como sinónimos, si el contexto no perturba la intención del emisor, es decir, si no se distorsiona el mensaje del interlocutor porque no se dé ambigüedad semántica."
Para ITIL V3 el conocimiento que poseen los colaboradores (conocimiento propio o propietario) y que han ido ganando a lo largo del tiempo, no sirve si no se adapta a estándares y se socializa. Siempre será recomendable documentar los procesos, apegarse a estándares de la industria y evitar que el conocimiento del negocio se acumule en solo algunas personas.
La documentación del proyecto de TI debe adecuarse a las necesidades establecidas y a la metodología o marco de referencia sobre el que se este desarrollando. Sin embargo existen documentos fundamentales de acuerdo a la etapa o ciclo de vida del sistema en que se encuentre.
El PMBOOK por ejemplo, establece la documentación administrativa y de control que debe asociarse al proyecto. ITIL nos da una idea de la documentación que debe existir para proporcionar los servicios de manera adecuada. Otros estándares específicos para la codificación como: JavaDoc o de documentación de usuario propuestos por el IEEE, deben ser establecidos por el documentador y seguidos por los programadores.
Las metodologías de desarrollo de software brindan una guía de la documentación que es necesaria tener, aunque de manera general siempre se requerirá crear: el catálogo de requerimientos, diccionario de datos, diagramas UML, el plan de trabajo, el plan de implementación o implantación, el plan de capacitación y el control de cambios.
Dependiendo del lenguaje en el cual se esta desarrollando el proyecto se debe establecer el patrón de documentación por ejemplo: JavaDoc, JSDoc, JSON, PHP, etc.
El siguiente diagrama muestra las diferentes etapas y áreas de un proyecto de TI y los documentos asociados a cada una de ellas:
Finalmente todos los archivos incluyendo la documentación de usuario , administrativa, presupuestal y procedimientos, deben colocarse en un repositorio bajo el cual se tenga un control de versiones. De manera personal recomiendo el uso de SVN Subversion o Git, aunque existen muchos más.
Una vez que se ha establecido el ambiente para el almacenamiento y control de la documentación y después de determinar cuales serán los documentos que han de realizarse a lo largo del proyecto, debe determinarse el formato en que serán capturados y distribuidos. Estos formatos pueden ser: formatos en Word u algún otro procesador de texto, LaTex, DocBook, etc.