|
Cómo evitar escribir la documentación: la ayuda interna
Copyright © 2000 Ernesto
De Spirito
Índice
Introducción
En un chiste de una edición pasada del Boletín para Desarrolladores definimos a la
documentación como "lo primero que el usuario pide y la cosa que lee (si
es que alguna vez la lee)." También pudimos haberla definido como "lo
primero que un desarrollador olvida y la última cosa que está dispuesto
a hacer (si es que está dispuesto a hacerla)."
Estas definiciones pueden sonar a broma, pero reflejan la pura realidad.
Bien, las compañías no tienen problemas: tienen escritores técnicos a
los que les pagan para escribir (y supuestamente les gusta), pero para
los desarrolladores solitarios o los pequeños equipos, los hechos de la
vida son:
- ULos usuarios no quieren leer la documentación
- Los desarrolladores no quieren y/o no les gusta escribirla
- Los usuarios reclaman la documentación
Pareciera que todos (desarrolladores y usuarios) podríamos ser felices
si no fuera por este último punto. ¿Por que los usuarios quieren la
documentación si después no van a leerla? Bueno, primero que todo,
algunos quieren la documentación porque en realidad sí la leerán.
Quieren una posibilidad de hacer cosas por ellos mismos sin depender de
nosotros. No obstante, la mayoría de los usuarios no la leerán, pero
pienso que la piden por una razón muy simple y entendible: miedo. ¿Miedo
de qué? Miedo de no obtener suficiente ayuda y soporte cuando se queden
trabados y no puedan seguir con nuestra aplicación por ellos mismos.
Creo que la mayoría de los usuarios que piden la documentación la
consideran el último recurso, y que disponer de este recurso en caso que
llegaran a necesitarlo los hace sentirse seguros. Lo que quieren es
soporte garantizado, y ven en la documentación esa garantía; una
garantía de calidad. Esto no significa que los usuarios van a leerla si
no obtienen soporte, pero quieren tener algo que mostrarle a alguien que
pudiera estar en posición de ayudarlos. Esto significa que -de un modo u
otro- eventualmente alguien leerá la documentación, y consiguientemente
tendremos que escribirla...
Ahora los hechos de la vida son:
- Los usuarios quieren/necesitan la documentación ==> hay que dárselas
- Los desarrolladores no quieren y/o no les gusta escribirla
¿Cuál es la solución? Algo intermedio: escribir sólo la mínima documentación
posible! ;) De nuevo, puede sonar un poco gracioso, pero en
realidad es un asunto muy serio. La documentación agrega valor a un
producto, así como también incrementa su costo, de modo que debemos
escribir sólo la suficiente documentación para satisfacer a los
usuarios.
El objetivo –entonces– es maximizar la satisfacción del usuario para
obtener el valor agregado mientras minimizamos nuestro esfuerzo a fin de
mantener el costo tan bajo como sea posible. ¿Se puede lograr esto?
Hasta cierto punto, sí. ¿Cómo? Pues hay diferentes técnicas para las
diferentes partes de la documentación:
Instrucciones de instalación
Una de las cosas más frustrantes para el usuario es no poder ser capaces
de instalar una aplicación. Se puede (Y DEBE) evitar esta parte de la
documentación proveyendo un instalador "a prueba de tontos".
InstallShield está bien, por ejemplo, y alcanza lo que hoy en día se
considera un estándar, aunque una vez estaba hablando por teléfono con
un usuario que me llamó para pedirme ayuda para instalar una aplicación:
Helpdesk: "Bueno, ahora haga doble-clic en el archivo SETUP.EXE"
Usuario: "Listo. Dice 'Esto instalará blah, blah, blah...'"
Helpdesk: "OK. Haga clic en el botón 'Aceptar'"
Usuario: "Ahora dice 'Lea los términos blah, blah, blah...'"
Helpdesk: "Haga clic en 'Estoy de acuerdo'."
Usuario: "Ahora dice 'Elija la instalación blah, blah, blah...'"
Helpdesk: "Haga clic en 'Típica' y luego en 'Siguiente'."
Usuario: "Ahora dice '¿Desea blah, blah, blah...'"
Helpdesk: "Haga clic en 'Siguiente'."
Usuario: "Ahora dice 'Instalación finalizada blah, blah, blah, ver LEAME?,
blah, blah, blah...'"
Helpdesk: "Haga clic en 'No' y luego en 'Finalizar' y listo."
Usuario: "Desapareció."
Helpdesk: "Perfecto, ya terminó la instalación."
Usuario: "Ah... Bien, pero... ¿Por qué no se puede instalar con un solo clic?"
Tiene razón. La mayoría de los asistentes de instalación no son "a
prueba de tontos"... El programa de instalación es la primera impresión
que un usuario tendrá de nuestra aplicación (y alguien dijo que las
primeras impresiones duran para siempre). Una instalación engorrosa no
dejará una buena impresión (los usuarios sentirán "es como las demás")
mientras que una instalación sencilla puede llegar a hacer maravillas
con la actitud del usuario frente a nuestra aplicación, así que es
importante tener esto en cuenta al elegir un instalador o al configurar
sus opciones.
Opciones de configuración
Algunas aplicaciones, como los clientes de email por caso, necesitan
algunos datos iniciales y/o el establecimiento de algunas opciones de
configuración antes que puedan ser totalmente operacionales. Puede
evitarse documentar esto si provee un asistente con suficiente información
visible sobre cada dato que le solicita al usuario.
Es algo decepcionante ver por ahí muchos "asistentes" que en realidad
no asisten para nada. Un texto que diga "Por favor ingrese su nombre en
el cuadro de texto de abajo:" me dice tanto como una etiqueta que
simplemente diga "Nombre:". Si dijera por ejemplo "Ingrese su nombre tal
como quiera que lo vean los destinatarios del correo que envíe:" ya me
dice mucho más. Por lo general los asistentes piden un dato por cada
pantalla así que sobra el lugar para poner descripciones significativas.
Tareas/Transacciones
He visto cientos -si no miles- de aplicaciones en mi corta vida, y me
considero a mí mismo un usuario avanzado, pero he encontrado muchas
bonitas aplicaciones shareware que no he podido usar por no saber cómo
hacer ciertas tareas (¡como por ejemplo comenzar a hacer algo!) y en
muchos casos no había documentación disponible... porque viene con la
registración!!! ¿Cómo se supone que voy a evaluar una aplicación y saber
si cubrirá mis necesidades si no la puedo usar? Pienso que a alguna
gente hay que recordarle que el concepto shareware significa "pruebe
antes de comprar"... Pero esto es para la anécdota, el punto es que en
otros casos la documentación estaba allí pero no me daba ninguna
pista...
La explicación de cada elemento del menú, cada cuadro de diálogo, y cada
control es necesaria, pero algunas veces no es suficiente. Tendemos a
pensar que con toda esa información debería ser obvio para el usuario
cómo realizar ciertas tareas, pero la realidad muestra que los usuarios
se ahogan en este mar de información... Lo que necesitan es algo más
directo que responda preguntas en su propia jerga como por
ejemplo "¿Cómo registro un pago?", y cosas como esas
que son las tareas o transacciones normales que los usuarios tienen que
realizar con nuestra aplicación.
La documentación de uno de estos "COMOs" podría leerse así:
- Haga clic en el menú 'Tablas'
- Haga clic en el elemento de menú 'Clientes...'. Aparecerá el cuadro
de diálogo 'Clientes'.
- Seleccione el cliente cuyo pago pago quiere registrar y haga clic en
el botón 'Pagos...'. Aparecerá el cuadro de diálogo 'Pagos'.
- Haga clic en 'Nuevo...'. Aparecerá el diálogo 'Nuevo pago'.
- Ingrese los datos del pago y haga clic en 'Aceptar' para registrar
el pago.
Muy bien, pero alguien podría preguntar, "¿Y por qué en lugar de yo
tener que seguir todas esas instrucciones no hay un botón allí para que
todo eso se haga solo?" El usuario tendría razón. Podemos usar las
capacidades de programación de los archivos de ayuda para automatizar
cosas como estas, pero si vamos a hacer el esfuerzo de programar,
podemos deshacernos del archivo de ayuda teniendo un menú COMO con una
estructura como esta:
En lugar de buscar en un archivo de ayuda, los usuarios pueden encontrar
información rápido de esta manera. También podríamos usar un cuadro de
diálogo con solapas, combos, opciones, etc. en vez de un menú. La clave
aquí es ayudar a los usuarios a encontrar lo que están buscando, y una
vez que sabemos lo que quieren hacer, hacerlo por ellos. Por ejemplo,
cuando el usuario haga clic en la opción "¿Cómo registrar el pago de un
cliente?" podemos mostrarle un cuadro de diálogo para que seleccione el
cliente al que quiere aplicar el pago y cuando haga clic en 'Aceptar' le
podemos mostrar el diálogo 'Nuevo Pago'. Simple y directo.
La "carne"
La carne de la documentación la constituye la explicación de cada menú,
cada cuadro de diálogo y cada control, así como también un glosario que
explique los términos poco comunes. Mencionamos antes que esta parte de
la documentación es necesaria, pero... ¿Cuán necesaria es? Por supuesto
que depende de la aplicación particular y del grupo de usuarios al que
está dirigida, pero para generalizar, podemos evitar escribir más de lo
necesario usando un esquema ABC:
- 5-10% de los elementos requieren una explicación detallada.
- 30-35% de los elementos pueden no ser obvios, pero una
explicación razonablemente breve sería suficiente.
- 60-70% de los elementos son bastante obvios y no requerirían
explicación, o sólo una muy pequeña.
Otra vez, podemos evitar escribir esta parte de la documentación usando
ayudas de herramientas (tool tips) que se muestran cuando el cursor se
mueve sobre un control, y usando mensajes que se muestran en un panel de
mensajes o en una ventana cuando se selecciona un control. Esto requiere
algo de programación, pero en Delphi y C++ Builder por ejemplo este
efecto se puede lograr de una forma transparente y reutilizable.
Recapitulando, al final en realidad tenemos que "escribir" algo -no
puede evitarse del todo-, pero es una cosa totalmente diferente. En
lugar de escribir una documentación completa, hasta la máxima extensión
posible podemos desarrollar nuestras aplicaciones de forma tal que no
necesiten documentación (la mejor forma de documentar una aplicación!)
y podemos usar la "ayuda interna" ("in-line help") que es más barata,
más fácil y más mantenible que la ayuda convencional (ya sea ésta
impresa o electrónica), sin mencionar que hasta podría ser mejor para
la mayoría de los usuarios ya que verían la ayuda allí mismo sin tener
que presionar F1 (una tecla que la mayoría de los principiantes nunca
presionarían, por ejemplo).
Por supuesto, no hay nada como un buen sistema de ayuda, pero la ayuda
interna es una forma costeable de proveer ayuda para pequeñas o grandes
aplicaciones de bajo presupuesto.
Este artículo fue publicado primero en nuestro Boletín para Desarrolladores, actualmente descontinuado.
|
