Funciones de un documentador de sistemas

"Para lograr una buena documentación son escenciales, la gramática y la ortografía pero, no lo es todo."

¿Cuáles son las funciones de un documentador?

Cuando uno se integra a un proyecto de desarrollo por lo general espera que el Arquitecto de Software le indique cuáles son las políticas y procesos para mantener actualizada la documentación de un sistema. En mi caso esto ocurrió aunque no de la manera que yo esperaba. La instrucción que yo recibí fue parecido a lo siguiente. "Ok, ya está, este es el sistema X y ahora debes hacer un manual de usuario", sin más comencé a revisar el programa con la intención de copiar algunas pantallas y comenzar a escribir el manual. Sin embargo no tenía una idea clara de que debía escribir y cómo, así que empece una búsqueda sobre estándares y recomendaciones para escribir documentos para los usuario.

El manual que construí estuvo bien, sin embargo no es el único tipo de documento que uno deberá crear. Así que una de las primeras tareas que un documentador debe saber que le serán encomendadas es la clasificación de la información que esta revisando. Y esto es muy importante pues le indicará el marco para dar el formato adecuado y complementar las partes estructurales mínimas que debe contener el documento.

Otra cosa que el documentador debe entender como una de sus funciones principales es el hecho de que su papel es el de un divulgador del proceso de análisis, desarrollo, construcción e implementación de un sistema de información, así que debe escribir pensando en sus lectores por lo que deberá "traducir" (aunque suene exagerado) lo que muchas veces entregan los programadores expertos en Java o en otro lenguaje. El trabajo del documentador no es fácil pues presupone que debe comprender de manera autónoma lo que otros hacen para dejar constancia de este trabajo para su posterior consulta.

A continuación les comparto un conjunto de conceptos y conocimientos que considero esenciales para realizar de manera adecuada el trabajo de la documentación de sistemas.

Una herramienta muy útil en el trabajo: El estandar IEEE - Std 1063-2001

Dividiremos la documentación en tipos: 

- Documentación técnica
- Documentación de Usuario
- Documentación administrativa relacionada a la gestión del proyecto

Un primer paso en la construcción de documentación de usuario (manuales, guías rápidas, descripción de módulos de software, etc) es conocer algunos estándares que nos ayuden en la confección de un buen documento para los usuarios finales del sistema o programa. 

El estandar IEEE - Std 1063-2001 nos brinda un marco de referencia donde se especifica el contenido, órden y formato de los elementos que debe contener un manual o cualquier otro documento orientado a los usuarios. Una descripción más detallada de este estandar y el link para su descarga, puede ser encontrado en la siguiente entrada. 

UML y la documentación técnica

El documentador acompaña con su actividad al equipo de desarrollo principalmente, pero en algunos lugares participara con varios equipos, incluyendo los de infraestructura e incluso los administradores.

Debido a la interacción de diferentes personas con diferentes formación e incluso, en equipos de desarrollo muy grandes, con diferentes idiomas, fue necesaria la creación de un lenguaje que permitirera que todos los actores involucrados en el desarrollo de un sistema pudieran comunicarse adecuadamente. El lenguaje creado se llama UML. 

UML es un lenguaje gráfico universal utilizado para el modelado de procesos, secuencias, objetos, relaciones, clases. De esta manera el arquitecto o analista del sistema puede transmitir un requerimiento adecuadamente a un programador y de esta manera evitar la confusión que podría ocasionar un texto mal redactado. Es deber de los documentadores en muchas empresas conocer a detalle el lenguaje UML para documentar de manera adecuada los requerimientos o casos de uso que se necesitan desarrollar. 

Así que conocer hacerca de UML a detalle es escencial. En el siguiente link encontrarás información sobre cómo realizar casos de uso usando UML. Da click aquí.

Metodologías para el desarrollo del Software

Conocer a fondo la metodología de desarrollo que utiliza tu empresa también es escencial para poder realizar un trabajo de documentación adecuado. La metodología utilizada proporcionará un marco de referencia para los documentos que deberán acompañar al producto de software. Por ejemplo en RUP necesitaremos casos de uso, pero en SCRUM se elaborarán historias de usuario. Así pues se necesita definir desde un principio cual será la metodología a utilizar y que documentos formaran parte del entregable final, con la intención de ir recavando esta información a lo largo del desarrollo.

He compartido un manual de SCRUM en el siguiente link.

La redacción técnica

Escribir, pero en realidad escribir bien no es un ejercicio que practiquen muy amenudo las personas involucradas con cuestiones técnicas, como los ingenieros. Así que leer un poco sobre lo básico de la redacción y la ortografía no es para nada oscioso. La redacción técnica tiene sus reglas y si nuestro trabajo consiste de escribir documentos legibles sobre tecnología es necesario conocerlas. 

El punto principal consiste, sin embargo, en evitar el uso de términos muy técnicos como por ejemplo: over loaded, por qué no usar sobrecarga. Lo anterior también nos lleva a la recomendación de utilizar, siempre que se pueda, los términos en español. Por ejemplo desplegar en lugar de deployar. (:s, wtf). Se debe agregar un glosario para términos o acrónimos que de antemano sabemos que un usuario común no comprenderá, por ejemplo: UML, o SCM, ya que en algunas ocasiones la abreviaciones son definidas por la organización o el grupo de trabajo y algún lector fuera de este ámbito podría entender o pensar en otro concepto. 

Finalmente, pero no menos importante, se debe escribir directo, sin rodeos y de manera clara y desde luego tratando de cuidar la ortografía. Un manual sobre redacción técnica se puede descargar desde el siguiente enlace

Si deseas más información sobre las funciones de un Documentador de Sistemas, te reocmiendo leer el siguiente enlace: Algunas otras funciones de un documentador de sistemas

Debido a la extensión del material que he ido recopilando a lo largo de los años no puedo compartir todo. Pero si estas interesado en información sobre algún tema en específico no dudes en compartir tu inquietud, estoy seguro que podré ayudarte. Si el texto ha sido de tu agrado e interés te recomiendo visitar el demás contenido y regalarme un click en g+. 

Finalmente no soy propietario de ninguno de los PDF's compartidos en este blog, los derechos de venta corresponden a sus autores, su divulgación a través de este medio es solo con caracter educativo, así que cualquier acción en mi contra sería simplemete ¡no cool!.