INSTITUTO TECNOLGICO DE COSTA RICA. ESCUELA DE COMPUTACIN.

PROGRAMA DE MAESTRIA EN COMPUTACIN, CURSO COMUNICACIN CIENTFICA (MC0100)

INSTITUTO TECNOLOGICO DE COSTA RICA DEPARTAMENTO DE COMPUTACION CURSO COMUNICACIN CIENTIFICA (MC-0100)

PREPARACION DE MANUALES DE USUARIO RECOMENDACIONES GENERALES Y NORMAS IEEE

Gabriel Vargas Acua, M.L.

n manual es un documento de apoyo para la realizacin de un proceso conocido. Puede tratarse de un material para conocer el proceso (instruccional) o para refrescar la memoria de un entendido (referencial). En el campo de la ingeniera, el manual es una herramienta permanentemente vinculada a los procesos complejos. En el rea de la computacin, este documento, cualquiera que sea el nivel, forma parte de los recursos del usuario y del diseador. J. M. Lannon seala que en ingeniera el manual es parte de la obra y que un defecto en su preparacin debe considerarse un defecto en el diseo completo. En forma general, los manuales estn formados de una combinacin de datos y de instrucciones. Un dato es una informacin que el usuario o el operador requieren para tomar decisiones en el manejo del equipo. Una instruccin es una indicacin de cmo debe procederse para lograr un efecto particular de, equipo. IEEE distingue dos tipos de instrucciones: acciones y pasos. Una accin es un acto especfico que ya no se puede subdividir; en cambio, un paso es un conjunto de acciones que cumplen un propsito

Condiciones generales de un manual

Lannon menciona las siguientes condiciones de la organizacin de un manual:

Ttulo claro y descriptivo de lo que se trata. El lector debe darse cuenta inmediata de cules son los alcances del material que consulta. Buena secuencia. Los aspectos tratados se ordenan segn una lgica que apoye el trabajo del usuario Explicaciones necesarias para operar el elemento: importancia del procedimiento, explicaciones detalladas, ejemplos..

Asimismo, seala algunos aspectos de forma: Advertencias, precauciones y notas complementarias Lenguaje apropiado: trminos inconfundibles, lenguaje directo, cumplimiento del paralelismo (simetra en enumeraciones; por ejemplo; una lista de instrucciones inicia toda con infinitivo) Formato accesible: numeracin de los pasos; imgenes para representar los objetos y acciones; subtitulos que permitan ubicar los contenidos; elementos tipogrficos que ayuden al lector (colores, recuadros, negritas).

INSTITUTO TECNOLGICO DE COSTA RICA. ESCUELA DE COMPUTACIN. PROGRAMA DE MAESTRIA EN COMPUTACIN, CURSO COMUNICACIN CIENTFICA (MC0100)

Finalmente, Lannon propone una estructura para un manual. No todos los componentes los considera obligatorios. Estructura bsica de un manual I. INTRODUCCION A. B. C. D. E. F. G. H. I. II. Definicin, beneficios y propsitos del procedimiento Audiencia propuesta Conocimientos bsicos requeridos por la audiencia Descripcin general del procedimiento Principios de operacin Materiales, equipos y condiciones especiales Definiciones necesarias Advertencias necesarias y notas convenientes Aspectos incluidos en el manual

INSTRUCCIONES PARA EL USO A. Primer paso importante 1. Definicin y propsito 2. Condiciones para este paso 3. Subdivisin de este paso B. Segundo paso importante ...

III.

CONCLUSION A. Revisin general del procedimiento B. Interrelacin entre pasos C. Manejo de problemas

Estndares de la IEEE (The Institute of Electrical and Electronics Engineers) La famosa y consolidada organizacin que norma los diferentes aspectos tcnicos de la ingeniera elctrica y electrnica, tambin dedica sus esfuerzos a la documentacin tcnica. Su trabajo sobre la documentacin para el usuario, ofrece muy consistentes recomendaciones. Seala IEEE que lo propio de un manual de usuario es que permite guiarse en la instalacin, operacin y manejo de software, siempre y cuando no implique la modificacin de cdigo. Los siguiente son tres pasos fundamentales para documentar un software: Identificar el software: su nombre, la interfaz del usuario con este Reconocer la audiencia a la cual se dirigir el manual. Esto se puede determinar por las caractersticas de la interaccin entre usuario y software: cantidad de interaccin, nivel, carcter directo o indirecto de esa interaccin. de los usuarios.

INSTITUTO TECNOLGICO DE COSTA RICA. ESCUELA DE COMPUTACIN. PROGRAMA DE MAESTRIA EN COMPUTACIN, CURSO COMUNICACIN CIENTFICA (MC0100)

Aplicar el criterio de funcionalidad del material para reconocer los dos grandes tipos de manuales: modo instruccional, aplicado para usuarios que deben aprender la manipulacin del software; modo referencial, dirigido a usuarios que requieren consultar el procedimiento de manipulacin.

Componentes de un manual de usuario A continuacin se sealan, en forma entremezclada, los diversos componentes de un manual de usuario segn los estndares de IEEE. Portada: nombre, versin y fecha del software, cobertura del software, partes del documento Restricciones: condiciones de propiedad y licencias Garantas: condiciones en que se proporciona el producto Tabla de contenidos: lista de ttulos generales Lista de ilustraciones: enumeracin de los elementos grficos que se han usado Introduccin: audiencia, propsito, uso del documento, documentos relacionados, convenciones, reporte de problemas Cuerpo del documento Modo de instruccin: alcances del manual, materiales requeridos, requerimientos para el manejo, precauciones y advertencias, procedimientos de operacin, informacin complementaria Modo de referencia: propsito, materiales, preparacin, inputs, precauciones y advertencias, parmetros, interrupcin y restauracin del funcionamiento, output, condiciones de error, informacin complementaria Condiciones de error: especificacin de los factores que causan cada tipo de error del software. Apendices: detalles del input y del output, cdigos, interacciones entre tareas y funciones, formato y estructura de archivos, reportes. Bibliografa: Referencias bibliogrficas Glosario: Expresiones tcnicas usadas. Acrnimos, abreviaturas, Indice: lista alfabtica de asuntos tratados

Ha podido verse que el manual es un documento decisivo en el manejo y operacin de los productos de ingeniera y, particularmente, de los generados en el campo de la computacin. En una encuesta planteada por Lannon a jefes de oficinas de desarrollo de software, se evidencia que aproximadamente el 30% del tiempo de trabajo de estos proofesionales se dedica a la documentacin del producto.

Bibliografa Lannon, John M. Technical Writing 5 ed. USA: Harper-Collins Publishers, 1990. IEEE Standards Collection Software Engineering. USA: IEEE, 1994.

INSTITUTO TECNOLGICO DE COSTA RICA. ESCUELA DE COMPUTACIN. PROGRAMA DE MAESTRIA EN COMPUTACIN, CURSO COMUNICACIN CIENTFICA (MC0100)