1

DOCUMENTACIN DE USUARIO
Ing. MSc. CELEDONIO MENDEZ
TCNICAS DE DOCUMENTACIN Y ARCHIVO
6
Contenido
6.1 Conceptos generales
6.2 Desarrollo de la documentacin
6.3 Estructura de la documentacin
6.4 Recomendaciones generales
6.1
CONCEPTOS GENERALES
DOCUMENTACIN DE USUARIO
Forma de distribucin
Interno
Documentacin de usuario que se encuentra
integrada y es accesible a travs del software.
Externo
Documentacin de usuario cuyo acceso no est
integrado en la operativa del software.
La forma externa no quiere decir que emplee una
distribucin no informtica, sino que se encuentra
apartada de la operacin del software.
De hecho la documentacin externa puede
distribuirse en CD, a travs de descargas desde la
web, etc.
Documentacin de usuario Conceptos Generales
Imortancia de !a ca!idad de !a
documentacin
A pesar de su importancia, las organizaciones productoras
de software suelen descuidar la calidad de la
documentacin de usuario.
En muchos casos la documentacin se prepara en el
ltimo minuto, por cumplir una obligacin y sin
concentrarse en considerarla como informacin
indispensable para el usuario.
LA DOCUMENTACIN DE USUARIO INADECUADA ES
UN PROBLEMA COMN EN LA INDUSTRIA DEL
SOFTWARE
Documentacin de usuario Conceptos Generales
"ENTA#AS $E LA $OC%&ENTACI'N
Ayuda al cliente a obtener todo el valor de su
inversin.
La operacin de sistemas complejos sin un
conocimiento detallado de los mismos puede dejar
sin uso un porcentaje importante de los mismos.
Una documentacin completa y til incrementa la
facilidad de uso del sistema.
Documentacin de usuario Conceptos Generales
2
Tios de documentos ( contenidos osib!es
La documentacin de usuario de un sistema de
software puede estar comprendida en uno o varios
documentos fsicos.
Un documento puede abordar uno o varios de los
siguientes mbitos:
Instalacin / desinstalacin.
Uso del sistema.
Administracin.
Un sistema de software puede disponer de manuales
diferentes para cada uno de los subsistemas que lo
componen.
Documentacin de usuario Conceptos Generales
&odos descriti)os
La documentacin de usuario puede adoptar dos modos
narrativos diferentes: formativo o referencia, en funcin de la
finalidad con la que el lector va a usar el texto:
Para aprender a trabajar con el software (modo
formativo)
Para refrescar la memoria, realizando consultas
puntuales (modo referencia).
A su vez, los textos formativos pueden orientar la exposicin
de sus contenidos para indicar al lector cmo realizar cada
tarea paso a paso. (orientados a tareas), o para transmitirle
la informacin y conocimientos tcnicos necesarios para
emplear el software de forma adecuada (orientados a la
informacin).
Documentacin de usuario Conceptos Generales
&odos descriti)os
Modos descriptivos
Formativo
Referencia
Orientado a tareas
Orientado a la
informacin
Documentacin de usuario Conceptos Generales
6.*
$ESARROLLO $E LA
$OC%&ENTACI'N
DOCUMENTACIN DE USUARIO
$esarro!!o de !a documentacin
Los factores que deben determinarse antes de
desarrollar la documentacin son:
Que documentos son necesarios.
Las caractersticas de la audiencia o audiencias
de la documentacin.
El modo descriptivo de cada documento.
Documentacin de usuario Desarrollo de la documentacin
En funcin de las caractersticas del sistema, de los
usuarios e incluso de parmetros del proyecto, es
necesario determinar cules son los documentos que
debern elaborarse.
As por ejemplo, un producto con desarrollo incremental
puede tener como requisitos en el contrato la
elaboracin de manuales de usuario para cada
subsistema entregado, o uno global para todo el
sistema.
$ocumentos necesarios $ocumentos necesarios
Documentacin de usuario Desarrollo de la documentacin
3
+ $ocumentos necesarios
Factores que pueden resultar tiles en su determinacin son:
Naturaleza del producto, fin previsto, entorno en el que se
emplear, complejidad de uso vista desde el punto de vista
del usuario. Cmo 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 informticos.
En los procesos de negocio gestionados por el sistema.
Tamao y complejidad del sistema, junto con las tecnologas
empleadas en su desarrollo y mantenimiento.
Requisitos contratados.
Documentacin de usuario Desarrollo de la documentacin
Caracter,sticas de !a audiencia
Audiencia: grupo de usuarios con caractersticas
similares, tanto de operacin con el sistema, como de
conocimientos y experiencia informtica y profesional.
Antes de comenzar el desarrollo de la documentacin
es importante clasificar a los usuarios del sistema por
audiencias, identificando las caractersticas clave.
La documentacin debe plantearse pensando en las
caractersticas y necesidades de la audiencia.
Documentacin de usuario Desarrollo de la documentacin
Criterios ara identi-icar audiencias
Algunos criterios tiles para identificar las audiencias y sus
caractersticas:
Educacin:Cul es el nivel educativo de la audiencia?
Actitud: Cul es la actitud de la audiencia?. Son
reacios al uso de ordenadores?. Presentan resistencia al
cambio?
Nivel de sofisticacin informtica. A ttulo de ejemplo,
Brockmann
[1]
identifica cinco niveles de sofisticacin
informtica de los usuarios, que se muestran en la pgina
siguiente.
Familiaridad con los procesos y negocio de la
aplicacin.
Documentacin de usuario Desarrollo de la documentacin
C!asi-icacin de usuarios C!asi-icacin de usuarios
Experto
Inexperto
Principiante
Intermedio
Intermitente
Conocimientos de
informtica
Muy poca o ninguna experiencia con ordenadores
Tratan volmenes reducidos de informacin
No confan en la informtica
Trabajadores operativos
Caractersticas
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 o
experto. Trabaja muy poco con el sistema.
Se conduce a travs de los mens y mensajes del sistema
Documentacin de usuario Desarrollo de la documentacin
6..
ESTR%CT%RA $E LA
$OC%&ENTACI'N
DOCUMENTACIN DE USUARIO
Estructura de !a documentacin
de usuario
Estructura de la documentacin es la manera de
organizar la informacin y dividirla en captulos as
como el orden de su presentacin.
La estructura afecta tanto a documentos impresos
como a documentos electrnicos.
Puede entregarse en uno o varios documentos.
La estructura debe ayudar a localizar y comprender la
informacin.
Documentacin de usuario Estructura de la documentacin
4
+ Estructura de !a documentacin
de usuario
Cuando la documentacin de un sistema se dirige a
audiencias diferentes debe emplearse uno de los
siguientes criterios:
Separar en secciones diferentes la informacin dirigida
a audiencias diferentes, identificando en la
introduccin de cada seccin la audiencia a la que va
dirigida.
Separar en documentos diferentes la informacin para
cada audiencia.
Documentacin de usuario Estructura de la documentacin
Recomendaciones de! est/ndar
IEEE 106.1*001 sobre !a estructura
El manual de un sistema puede consistir en uno o ms
documentos, y cada documento puede comprender uno o
varios volmenes.
Son recomendables (aunque no obligatorio) las siguientes
divisiones dentro de cada documento:
Documentos impresos: Captulos, temas y sub-temas.
Documentos electrnicos: temas.
La unidad de presentacin para los primeros es la pgina, y
para los segundos la pantalla.
Cada pgina o pantalla debe tener una identificacin nica (por
ejemplo el ttulo del captulo y el n de pgina), que debe
aparecer al ser impresa por el usuario.
Documentacin de usuario Estructura de la documentacin
Recomendaciones del estndar
IEEE 1063-2001 sobre la estructura
Los documentos impresos no deben tener ms de tres
niveles de subdivisin dentro de un captulo. As, por
ejemplo, un sub-tema con nivel 1.2.3.4 debe ser el mayor
nivel de sub-divisin.
Los documentos electrnicos deben permitir acceder a
cualquier informacin con menos de 3 saltos (links) desde
la pgina inicial.
Documentacin de usuario Estructura de la documentacin
Recomendaciones del estndar
IEEE 1063-2001 sobre la estructura
Los documentos que contengan informacin en varios
modos descriptivos (formativo y de referencia) deben
estar claramente separados en captulos diferentes, o al
menos en temas diferentes o manteniendo formatos
tipogrficos distintos.
La documentacin en modo de referencia debe estar
estructurada para facilitar la bsqueda y acceso a los
diferentes elementos. Por ejemplo, ordenando
alfabticamente una lista de comandos, o de informes de
error.
Documentacin de usuario Estructura de la documentacin
Recomendaciones del estndar
IEEE 1063-2001 sobre la estructura
Recomendaciones del estndar
IEEE 1063-2001 sobre la estructura
Cada documento debe incluir:
INFORMACIN DE IDENTIFICACIN
Ttulo del documento
Versin del documento y fecha de publicacin
Nombre del producto de software y versin
Organizacin que edita el documento
TABLA DE CONTENIDOS (ndice)
INTRODUCCIN
Audiencia
Alcance y propsito del documento
Descripcin general del propsito y funcionalidad
del software, as como del entorno de operacin
Documentacin de usuario Estructura de la documentacin
Recomendaciones del estndar
IEEE 1063-2001 en la estructura
Recomendaciones del estndar
IEEE 1063-2001 en la estructura
Informacin crtica
La informacin crtica debe aparecer en una
ubicacin destacada de la documentacin.
Las advertencias de carcter general deben
incluirse en la introduccin del documento.
Las advertencias particulares deben aparecer
en la misma pgina o pantalla en la que se da
informacin del procedimiento implicado
!
Documentacin de usuario Estructura de la documentacin
5
Recomendaciones del estndar
IEEE 1063-2001 en la estructura
La informacin debe ser completa
Si es en modo formativo debe incluir descripcin
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 informacin debe ser actual y acorde a la versin
del software indicada.
Documentacin de usuario Estructura de la documentacin
Recomendaciones del estndar
IEEE 1063-2001 en la estructura
Recomendaciones del estndar
IEEE 1063-2001 en la estructura
Componentes recomendados para la documentacin de usuario:
CO&PONENTE 2O3LIGATORIO4
Informacin de identificacin S
Tabla de contenidos
S, para documentos de
ms de 8 pginas
Lista de imgenes Opcional
Introduccin S
Informacin sobre el uso de la
documentacin
S
Informacin conceptual de las
Funcionalidades generales
S
Documentacin de usuario Estructura de la documentacin
Recomendaciones del estndar
IEEE 1063-2001 en la estructura
Recomendaciones del estndar
IEEE 1063-2001 en la estructura
Componentes recomendados para la documentacin de usuario
CO&PONENTE 2O3LIGATORIO4
Procedimientos S, en modo formativo
Informacin de comandos de software S, en modo referencia
Mensajes de error y solucin de problemas S
Glosario
S, si la documentacin incluye trminos
desconocidos para la audiencia
Fuentes de informacin adicionales Opcional
ndice S, en documentos de ms de 40 pginas
Opcin de bsqueda
S, en documentacin sobre formato
electrnico
Documentacin de usuario Estructura de la documentacin
6.5
RECO&EN$ACIONES
GENERALES
DOCUMENTACIN DE USUARIO
Recomendaciones 6enera!es
LEGI3ILI$A$
La documentacin impresa y electrnica 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 fcilmente legibles
sobre el color de fondo empleado.
La documentacin impresa debe mantenerse legible si el
usuario agranda o reduce la ventana de visualizacin.
En la documentacin electrnica deben considerarse
tambin las combinaciones de colores previendo el caso que
el usuario utilice una impresora monocromtica.
Documentacin de usuario Recomendaciones generales
+ LEGI3ILI$A$
El estndar IEEE 1063, por ejemplo, da algunas
recomendaciones especficas como:
No abusar de las letras maysculas, indicando que no
se emplee en ms de 25 palabras seguidas.
No emplear en los textos electrnicos letras menores
de 3mm. (aprox. 7,5 puntos).
CORRECCI'N
Los textos deben ser lxica, ortogrfica y sintcticamente
correctos.
Documentacin de usuario Recomendaciones generales
6
El documento debe emplear de forma consistente la
terminologa 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 caractersticas
grficas homogneas: cabeceras, pies de pgina, estilos de
ttulos y prrafos, mrgenes, estilos de vietas, etc.
Las convenciones empleadas para mostrar las advertencias y
notas resaltadas deben presentarse con las mismas
caractersticas de estilo en todo el documento
CONSISTENCIA EN LA TER&INOLOG7A
8 EN EL FOR&ATO
Documentacin de usuario Recomendaciones generales
Contenido
6.1 Conceptos generales
6.2 Desarrollo de la documentacin
6.3 Estructura de la documentacin
6.4 Recomendaciones generales
Gracias por su atencin