PDF. Desarrollo de Interfaces. Tema 10
PDF. Desarrollo de Interfaces. Tema 10
PDF. Desarrollo de Interfaces. Tema 10
Documentación de
aplicaciones: Ayudas
10
/ 1. Introducción y contextualización práctica 3
/ 4. Tablas de contenido 6
/ 5. Tipos de documentación 6
/ 6. Tipos de manuales 7
/ 11. Bibliografía 15
© MEDAC 978-84-18983-19-1
Reservados todos los derechos. Queda rigurosamente prohibida, sin la autorización escrita de los titulares del copyright,
bajo las sanciones establecidas en las leyes, la reproducción, transmisión y distribución total o parcial de esta obra por
cualquier medio o procedimiento, incluidos la reprografía y el tratamiento informático.
Identificar sistemas de generación de ayudas.
Confeccionar tutoriales.
En concreto, se trata de ficheros de ayuda, manuales y demás guías de uso y/o mantenimiento, ya sean dirigidas
para los usuarios de la aplicación, para equipos de soporte o incluso para otros diseñadores.
Para un sistema software, es especialmente importante contar con una documentación completa y que a la vez sea
sencilla de consultar. Los motivos para ello son varios, por ejemplo, conseguir la mejora de la comprensión de uso
de una aplicación por parte de un usuario, independientemente de su perfil.
Un fichero de ayuda es, por tanto, un documento que contiene toda la información que puede servir de ayuda o de
manual para los usuarios de la herramienta sobre la que se ha desarrollado. En este tema, nos vamos a centrar en los
ficheros de ayuda en formato digital.
Es importante conocer la estructura general de cualquier fichero de ayuda. Estos suelen estar compuestos por dos
partes claramente diferenciadas: mapa de fichero y la vista de información.
El mapa de fichero, como su propio nombre indica, constituye una especie de mapa de navegación del sistema de
ayuda, asociando identificadores para cada uno de los temas contenidos a las URL donde se encuentra el contenido
relativo al tema seleccionado.
Por otro lado, la vista de información es la parte que se muestra al usuario, habitualmente en forma de índice,
glosario, tabla de contenidos e incluso buscador de temas.
Es posible encontrar múltiples tipos de formatos digitales para la creación y posterior consulta de ficheros de ayuda:
• HLP
Este nuevo formato incluía ciertas mejoras sobre HLP, por eso quedó incluido a partir de Windows Vista. Si
bien es cierto que desde Windows 7 solo aparece como ayuda para algunas aplicaciones.
• HPJ
Se trata de ficheros que utilizan IPF, un lenguaje muy similar a HTML. Son utilizados sobre todo para ayuda
en línea e hipertexto.
• JavaHelp
Finalmente, encontramos este último tipo de formato de fichero de ayuda que será tratado en el desarrollo
de este capítulo. Reciben este nombre tanto el formato de ficheros de ayuda en línea como el sistema que se
encarga de su generación.
Este tipo de ficheros están implementados en Java y se utilizan para la generación de ayuda de aplicaciones
desarrolladas en Java.
Esta herramienta permite la creación de ficheros de ayuda para Windows. Está formada por un editor de
imágenes, el administrador de proyectos y el compilador, este último
es clave para el desarrollo de manuales y ayuda, puesto que permite
reducir el tamaño final para su posterior distribución. Para descargar,
esta herramienta está disponible en este enlace. Tras la descarga, se
ejecuta el instalador de software htmlhelp.exe.
b. Help Maker
/ 4. Tablas de contenido
Una tabla de contenido permite reflejar la estructura y contenido de un documento. Se encuentra esquematizada
en varios niveles de elementos entre los que se distinguen títulos y subtítulos. Aunque el diseño dependerá del
desarrollador y de otros muchos factores, algunas de las características típicas son:
/ 5. Tipos de documentación
En función del tipo de aplicación, del tipo de usuario o de la fase concreta en la que se encuentra la aplicación, es
posible realizar diferentes clasificaciones en cuanto los tipos de documentación se refiere.
TÉCNICO EN DESARROLLO DE APLICACIONES MULTIPLATAFORMA
/7 MEDAC · Instituto Oficial de Formación Profesional
A grandes rasgos, podemos dividir la documentación de aplicaciones software en dos grandes grupos:
• Documentación de salida: Se trata de los informes resultantes de aplicar las pruebas, definidas en el
punto anterior, sobre el programa.
• Documentación técnica: Pertenece a este grupo el resto de documentación: guías, hojas de especificaciones,
manuales, etc. Al igual que en el caso anterior, puede dividirse en dos grupos:
• Documentación interna: Se trata de los comentarios incluidos por el desarrollador en el código, que
deben describir distintos aspectos sobre el mismo. Se debe incidir en la importancia de realizar un
programa ordenado y claro, en el que los comentarios ayuden a entender el código, pero este, de por sí,
debe ser claro. En este ámbito, debe tenerse en cuenta lo siguiente:
• Comienzos de módulos
/ 6. Tipos de manuales
Existen tipos de manuales y guías diferentes entre sí con relación al contenido de cada uno y a su manera de utilización.
El manual de usuario contiene la información necesaria para facilitar al usuario la comprensión y utilización
del programa desarrollado en diferentes ámbitos: formación del usuario, guía de consulta ante dudas, ayuda
para detectar y corregir errores, etc.
Aunque no hay ninguna norma sobre su elaboración, debe tratarse, por tanto, de un documento que sea
amigable y claro para el usuario, ya que, al fin y al cabo, es quien va a utilizarlo. Para ello, es aconsejable el uso
de imágenes y gráficos, textos claros y concisos, ejemplos ilustrativos, etc.
• Guía de referencia: Estas suelen desarrollarse para usuarios con cierto conocimiento y experiencia en el
uso de la aplicación.
Por ello, suelen contener información asociada a aspectos más técnicos: relación de mensajes de error y
su posible origen, tipos de datos de entrada permitidos en la aplicación, comandos aceptados, etc.
Esta herramienta permite la creación de documentos de ayuda muy completos que incluye tablas de contenidos,
motor de búsqueda, glosario, sección de favoritos…
Para crear un sistema de ayuda con JavaHelp, se deben seguir un conjunto de pasos secuenciados.
4. Se construye un fichero JAR que incluya todos los ficheros y permita mejorar
su distribución. Fig. 11. Icono JavaHelp.
TÉCNICO EN DESARROLLO DE APLICACIONES MULTIPLATAFORMA
/9 MEDAC · Instituto Oficial de Formación Profesional
• Especificar organización
• Diseñar temas
• Diversos repositorios
Tras la creación de todos los ficheros, el directorio contenedor queda de la siguiente forma:
Es fundamental que los ficheros HTML estén en un directorio bajo ./help, ya que, en caso contrario, la aplicación
no funcionará.
1. map_file.jhm. Este archivo se encarga de mapear cada uno de los HTML de ayuda creados indicando su
ruta y un identificador para cada uno de estos ficheros, a través del cual serán referenciados desde el resto
de la aplicación.
Código 1. map_file.jhm.
2. Fichero toc.xml. Es un fichero que recoge la tabla de contenidos y su índice. La estructura se basa en ‘tocitems’
para indicar cada uno de los elementos en los que se organiza la tabla.
Código 2. toc.xml.
TÉCNICO EN DESARROLLO DE APLICACIONES MULTIPLATAFORMA
/ 11 MEDAC · Instituto Oficial de Formación Profesional
3. Fichero indice.xml es un fichero que recoge la tabla del índice. La estructura se basa en ‘indexitems’ para
indicar cada uno de los elementos en los que se organiza el índice.
Código 3. indice.xml.
4. Fichero help_set.hs. Este último fichero de configuración contiene a los anteriores. En él se describen las
secciones relativas a las vistas.
Código 4. help_set.hs.
• Import javax.help.*: Permite utilizar los ficheros que hemos creado desde una aplicación Java. Incluye la clase
HelpSet y HelpBroker, que se utilizarán posteriormente.
TEMA 10. DOCUMENTACIÓN DE APLICACIONES: AYUDAS
Desarrollo de interfaces / 12
La inclusión de estos paquetes permitirá trabajar con las siguientes clases y métodos:
• Clase HelpSet: Posibilitará usar los ficheros del sistema de ayuda. Métodos:
• Clase HelpBroker: Permite visualizar el contenido de la ayuda desde la aplicación. Principales métodos:
• enableHelp: Hace referencia al tema o topic que se debe visualizar al pulsar una tecla de ayuda sobre un
componente determinado.
/**
* Hace que el item del menu y la pulsacion de F1 visualicen la ayuda.
*/
private void ponLaAyuda() {
try {
// Carga el fichero de ayuda
File fichero = new File(“../help/help_set.hs”);
URL hsURL = fichero.toURI().toURL();
// Crea el HelpSet y el HelpBroker
HelpSet helpset = new HelpSet(getClass().getClassLoader(), hsURL);
HelpBroker hb = helpset.createHelpBroker();
} catch (Exception e) {
e.printStackTrace();
}
}
• Página principal
• Capítulo 1, 2, 3 y 4. (Todos los ficheros de ayuda en formato .html se encuentran dentro de la ruta html/capitulos).
Nudo: Se diseñan los ficheros indicando la ruta en la que se encuentra los ficheros en los que aparece la ayuda.
Desenlace:
Fichero map_file.jhm:
Fichero toc.xml:
Fichero index.xml:
Existen diferentes tipos de documentación que se ajustan a la aplicación en cada caso. Podemos hablar, a grandes
rasgos, de la documentación de pruebas y la documentación técnica. La primera queda divida en documentación de
entrada y de salida, mientras que la de tipo técnico se subdivide en documentación interna y externa.
La ayuda genérica es el tipo de ayuda que recoge toda la información de la aplicación. Podríamos decir que se trata
del manual completo de uso del sitio. Para localizar la información que sea de utilidad en cada momento, habrá que
navegar por el mapa del sitio.
Ahora bien, la ayuda sensible al contexto es una ayuda concisa sobre la funcionalidad u operación que se está
realizando en cada momento. Habitualmente, aparece accesible o cada vez es más habitual y aconsejable que así se
haga, desde cada ventana, cuadro de texto o acción en la que se incluya. Suele aparecer enlazada en botones con el
símbolo de interrogación ? y, en ocasiones, con la letra i (información).
/ 11. Bibliografía
Fernández, A., García-Miguel, B. y García-Miguel, D. (2020). Desarrollo de Interfaces (1.a ed.). Madrid, España: Síntesis.