TDA 06 Documentacion Del Usuario

1

DOCUMENTACIÓN DE USUARIO

Ing. MSc. CELEDONIO MENDEZ

TÉCNICAS DE DOCUMENTACIÓN Y ARCHIVO

6

Contenido

6.1 Conceptos generales

6.2 Desarrollo de la documentación

6.3 Estructura de la documentación

6.4 Recomendaciones generales

6.1

CONCEPTOS GENERALES

DOCUMENTACIÓN DE USUARIOForma de distribución

Interno

Documentación de usuario que se encuentra integrada y es accesible a través del software.

Externo

Documentación de usuario cuyo acceso no está integrado en la operativa del software.

La forma externa no quiere decir que emplee una distribución no informática, sino que se encuentra apartada de la operación del software.

De hecho la documentación externa puede distribuirse en CD, a través de descargas desde la web, etc.

Documentación de usuario Conceptos Generales

Importancia de la calidad de la documentación

A pesar de su importancia, las organizaciones productorasde software suelen descuidar la calidad de ladocumentación de usuario.

En muchos casos la documentación se prepara en elúltimo minuto, por cumplir una obligación y sinconcentrarse en considerarla como informaciónindispensable para el usuario.

LA DOCUMENTACIÓN DE USUARIO INADECUADA ES UN PROBLEMA COMÚN EN LA INDUSTRIA DEL

SOFTWARE


VENTAJAS DE LA DOCUMENTACIÓN

� Ayuda al cliente a obtener todo el valor de su inversión.

� La operación de sistemas complejos sin un conocimiento detallado de los mismos puede dejar sin uso un porcentaje importante de los mismos.

� Una documentación completa y útil incrementa la facilidad de uso del sistema.


2

Tipos de documentos y contenidos posibles

La documentación de usuario de un sistema de software puede estar comprendida en uno o varios documentos físicos.

Un documento puede abordar uno o varios de los siguientes ámbitos:

• Instalación / desinstalación.

• Uso del sistema.

• Administración.

Un sistema de software puede disponer de manuales diferentes para cada uno de los subsistemas que lo componen.


Modos descriptivosLa documentación de usuario puede adoptar dos modosnarrativos diferentes: formativo o referencia, en función de lafinalidad con la que el lector va a usar el texto:

�Para aprender a trabajar con el software (modoformativo)

�Para refrescar la memoria, realizando consultaspuntuales (modo referencia).

A su vez, los textos formativos pueden orientar la exposiciónde sus contenidos para indicar al lector cómo realizar cadatarea paso a paso. (orientados a tareas), o para transmitirlela información y conocimientos técnicos necesarios paraemplear el software de forma adecuada (orientados a lainformación).


Modos descriptivos

Modos descriptivos

Formativo

Referencia

Orientado a tareas

Orientado a lainformación


6.2DESARROLLO DE LA DOCUMENTACIÓN


Desarrollo de la documentación

Los factores que deben determinarse antes de desarrollar la documentación son:

� Que documentos son necesarios.

� Las características de la audiencia o audiencias de la documentación.

� El modo descriptivo de cada documento.

Documentación de usuario Desarrollo de la documentación

En función de las características del sistema, de los usuarios e incluso de parámetros del proyecto, es necesario determinar cuáles son los documentos que deberán elaborarse.

Así por ejemplo, un producto con desarrollo incremental puede tener como requisitos en el contrato la elaboración de manuales de usuario para cada subsistema entregado, o uno global para todo el sistema.

Documentos necesariosDocumentos necesarios


3

… Documentos necesariosFactores que pueden resultar útiles en su determinación son:

� Naturaleza del producto, fin previsto, entorno en el que se empleará, complejidad de uso vista desde el punto de vista del usuario. Cómo de complejo es instalar, operar y mantener el sistema.

� Nivel de conocimientos de los usuarios, instaladores y personal de mantenimiento.

� En el uso de sistemas informáticos.

� En los procesos de negocio gestionados por el sistema.

� Tamaño y complejidad del sistema, junto con las tecnologías empleadas en su desarrollo y mantenimiento.

� Requisitos contratados.


Características de la audienciaAudiencia : grupo de usuarios con características similares, tanto de operación con el sistema, como de conocimientos y experiencia informática y profesional.

Antes de comenzar el desarrollo de la documentación es importante clasificar a los usuarios del sistema por audiencias, identificando las características clave.

La documentación debe plantearse pensando en las características y necesidades de la audiencia.


Criterios para identificar audiencias

Algunos criterios útiles para identificar las audiencias y sus características:

� Educación :¿Cuál es el nivel educativo de la audiencia?

� Actitud : ¿Cuál es la actitud de la audiencia?. ¿Son reacios al uso de ordenadores?. ¿Presentan resistencia al cambio?

� Nivel de sofisticación informática . A título de ejemplo, Brockmann[1] identifica cinco niveles de sofisticación informática de los usuarios, que se muestran en la página siguiente.

� Familiaridad con los procesos y negocio de la aplicación.


Clasificación de usuarios Clasificación de usuarios

Experto

Inexperto

Principiante

Intermedio

Intermitente

Conocimientos de

informática

� Muy poca o ninguna experiencia con ordenadores� Tratan volúmenes reducidos de información� No confían en la informática� Trabajadores operativos

Características

� Alguna experiencia con ordenadores� Pueden comprender conceptos aislados� Emplean ejemplos concretos� Emplean siempre las opciones por defecto

� Usuario novel con pocos meses de experiencia con computadores� Comienza a enlazar conceptos aislados� Emplea acciones por defecto y sus opciones.

� Comprende las relaciones entre conceptos aislados.� Tiene un nivel alto de autoconfianza.� Comprende el lenguaje abstracto

� Puede ser inexperto, principiante, intermedio oexperto. Trabaja muy poco con el sistema.

� Se conduce a través de los menús y mensajes del sistema


6.3ESTRUCTURA DE LA DOCUMENTACIÓN


Estructura de la documentaciónde usuario

• Estructura de la documentación es la manera de organizar la información y dividirla en capítulos así como el orden de su presentación.

• La estructura afecta tanto a documentos impresos como a documentos electrónicos.

• Puede entregarse en uno o varios documentos.

• La estructura debe ayudar a localizar y comprender la información.

Documentación de usuario Estructura de la documentación

4

… Estructura de la documentaciónde usuario

• Cuando la documentación de un sistema se dirige a audiencias diferentes debe emplearse uno de los siguientes criterios:

�Separar en secciones diferentes la información dirigida a audiencias diferentes, identificando en la introducción de cada sección la audiencia a la que va dirigida.

�Separar en documentos diferentes la información para cada audiencia.


Recomendaciones del estándar IEEE 1063-2001 sobre la estructura

� El manual de un sistema puede consistir en uno o más documentos, y cada documento puede comprender uno o varios volúmenes.

� Son recomendables (aunque no obligatorio) las siguientes divisiones dentro de cada documento:

• Documentos impresos: Capítulos, temas y sub-temas.

• Documentos electrónicos: temas.

La unidad de presentación para los primeros es la página, y para los segundos la pantalla.

Cada página o pantalla debe tener una identificación única (por ejemplo el título del capítulo y el nº de página), que debe aparecer al ser impresa por el usuario.


Recomendaciones del estándar IEEE 1063-2001 sobre la estructura

� Los documentos impresos no deben tener más de tres niveles de subdivisión dentro de un capítulo. Así, por ejemplo, un sub-tema con nivel 1.2.3.4 debe ser el mayor nivel de sub-división.

� Los documentos electrónicos deben permitir acceder a cualquier información con menos de 3 saltos (links) desde la página inicial.


Recomendaciones del estándarIEEE 1063-2001 sobre la estructura

� Los documentos que contengan información en varios modos descriptivos (formativo y de referencia) deben estar claramente separados en capítulos diferentes, o al menos en temas diferentes o manteniendo formatos tipográficos distintos.

� La documentación en modo de referencia debe estar estructurada para facilitar la búsqueda y acceso a los diferentes elementos. Por ejemplo, ordenando alfabéticamente una lista de comandos, o de informes de error.




Cada documento debe incluir:

INFORMACIÓN DE IDENTIFICACIÓN

�Título del documento�Versión del documento y fecha de publicación�Nombre del producto de software y versión�Organización que edita el documento

TABLA DE CONTENIDOS (índice)

INTRODUCCIÓN�Audiencia�Alcance y propósito del documento�Descripción general del propósito y funcionalidad

del software, así como del entorno de operación


Recomendaciones del estándarIEEE 1063-2001 en la estructuraRecomendaciones del estándarIEEE 1063-2001 en la estructura

Información crítica�La información crítica debe aparecer en una

ubicación destacada de la documentación.

�Las advertencias de carácter general deben incluirse en la introducción del documento.

�Las advertencias particulares deben aparecer en la misma página o pantalla en la que se da información del procedimiento implicado

!


5

Recomendaciones del estándarIEEE 1063-2001 en la estructura

�La información debe ser completa

� Si es en modo formativo debe incluir descripción suficiente para que los usuarios con menor experiencia puedan realizar eficientemente las funciones descritas.

� En modo referencia se deben incluir todas las instancias de los elementos seleccionados.

�La información debe ser actual y acorde a la versión del software indicada.



Componentes recomendados para la documentación de u suario:

COMPONENTE ¿OBLIGATORIO?

Información de identificación Sí

Tabla de contenidosSí, para documentos demás de 8 páginas

Lista de imágenes Opcional

Introducción Sí

Información sobre el uso de ladocumentación

Sí

Información conceptual de las Funcionalidades generales

Sí



Componentes recomendados para la documentación de u suario

COMPONENTE ¿OBLIGATORIO?

Procedimientos Sí, en modo formativo

Información de comandos de software Sí, en modo referencia

Mensajes de error y solución de problemas Sí

GlosarioSí, si la documentación incluye términosdesconocidos para la audiencia

Fuentes de información adicionales Opcional

Índice Sí, en documentos de más de 40 páginas

Opción de búsquedaSí, en documentación sobre formatoelectrónico


6.4RECOMENDACIONES

GENERALES


Recomendaciones generales

LEGIBILIDADLa documentación impresa y electrónica debe ser legible para el usuario, teniendo en cuenta la distancia que se empleará en las condiciones normales del entorno de consulta.

Deben emplearse tipos de letra y colores fácilmente legibles sobre el color de fondo empleado.

La documentación impresa debe mantenerse legible si el usuario agranda o reduce la ventana de visualización.

En la documentación electrónica deben considerarse también las combinaciones de colores previendo el caso que el usuario utilice una impresora monocromática.

Documentación de usuario Recomendaciones generales

… LEGIBILIDAD

El estándar IEEE 1063, por ejemplo, da algunas recomendaciones específicas como:

�No abusar de las letras mayúsculas, indicando que no se emplee en más de 25 palabras seguidas.

�No emplear en los textos electrónicos letras menores de 3mm. (aprox. 7,5 puntos).

CORRECCIÓNLos textos deben ser léxica, ortográfica y sintácticamente correctos.


6

El documento debe emplear de forma consistente la terminología empleada para nombrar los elementos de interfaz del usuario, nombres de operaciones, funciones, procesos y conceptos claves del sistema.

Asimismo debe respetar en todo el documento características gráficas homogéneas: cabeceras, pies de página, estilos de títulos y párrafos, márgenes, estilos de viñetas, etc.

Las convenciones empleadas para mostrar las advertencias y notas resaltadas deben presentarse con las mismas características de estilo en todo el documento

CONSISTENCIA EN LA TERMINOLOGÍAY EN EL FORMATO


Contenido

6.1 Conceptos generales

6.2 Desarrollo de la documentación

6.3 Estructura de la documentación

6.4 Recomendaciones generales

Gracias por su atención

TDA 06 Documentacion Del Usuario

Documents

Transcript of TDA 06 Documentacion Del Usuario