"Conocer a detalle el proceso o sistema para el cual se requiere el manual, es la columna vertebral de toda buena documentación de usuario"
Recomendaciones para escribir un manual de usuario
Recomendaciones para escribir un manual de usuario
El proceso de creación de un manual de usuario es cosa sencilla siempre y cuando se tenga en cuenta algunos puntos, los cuales deben seguirse en secuencia para no perdernos. El primer paso para escribir el manual sería: Identificar al usuario de la documentación o ¿quienes serán los lectores potenciales del documento?. Esto nos ayudará a ubicar cuál es el nivel técnico que se deberá utilizar en el documento y de alguna manera a planter su contenido.
El segundo paso será definir su tabla de contenidos. Necesitamos saber que información será colocada en él y en qué órden. Una buena práctica es colocar la tabla de contenidos en una matriz, en una hoja de cálculo, para ir señalando el avance de cada tema o proceso y de esa manera conocer el avance de lo que vamos escribiendo y su relación.
Tercero Organizar el contenido. Una pregunta recurrente es ¿qué se debe colocar en un manual de usuario o cómo se debe organizar?. Bien yo utilizó dos aproximaciones: Colocar en el índice los casos de uso y clasificarlos de acuerdo a los usuarios que los utilizan o organizar la información por funcionalidad.
Por ejemplo, supongamos que se diseño un programa de punto de venta y algunos de sus casos de uso son:
- Dar de alta un producto
- Modificar el precio del producto
- Iniciar venta
- Terminar venta
- Revisar existencias
Pues bien puede colocarse una lista con los casos de uso y comenzar a describirlos o podemos organizar el índice de acuerdo a las funcionalidades o a los procesos que se pueden realizar en el sistema, por ejemplo:
- Realizar una venta (este proceso seguro necesita incluir los casos de uso Iniciar venta y terminar venta)
- Revisar inventario (en este proceso quiza se necesite cargar nuevos productos o modificar el precio de alguno y revisar las existencias en el almacen).
Cuarto Recopilar y clasificar la información para cada tema o subtema dentro del documento. Aunque este punto se coloca en el cuarto lugar es indispensable que contemos con un almacen de información antes de la elaboración del documento. Contar con un repositorio de información nos brinda la posibilidad de tener un almacen centralizado de información, para que buscarla y clasificarla sea más facil. (puedes ver como instalar SVN en tu organización en el siguiente link.
Una vez que hemos cumplido con los cuatro puntos anteriores debemos elegir una estructura o marco de referencia formal para nuestro manual. De manera personal utilizo como referencia el estandar IEEE std-1063-2001. En el se especifican las partes que debe contener cualquier documentación de usuario.
Ahora si debemos comenzar a escribir el manual, aunque antes debemos decidir en qué formato y con qué software será creado, mi recomendación es DocBook (puedes ver más información de su uso en el siguiente tutorial de DocBook). Debe considerarse que un manual esta diseñado para diferentes perfiles de usuario, así que aveces conviene realizar diferentes versiones para que el actor en turno pueda ejecutar todas las funciones que permita su perfil. Por lo tanto debe ser claro y descriptivo, es decir, no dejar nada a la imaginación, ni a las suposición del usuario, dejar claras las notas o prerequisitos que el usuario requerirá para ejecutar el procedimiento sin problemas, deberá contener imágenes claras y detalladas las cuáles deberán colocarse en un índice y contar con una descripción de la imagen. Un vez que el manual se ha terminado deberá ser evaluado y revisado por los programadores o los ingenieros de pruebas con la intención de validar que sus indicaciones son adecuadas y conducen a un resultado exitoso si se siguen al pie.
Es seguro que escribir un manual o cualquier documento técnico requieren, de quien lo escribe, habilidades, destresas y conocimientos sólidos sobre la gramática, redacción y ortografía con la finalidad de que este bien hecho. Se debe recordar además que una buena documentación, en este caso un buen manual, puede hacer la diferencia entre el éxito o el fracaso del sistema en su implementación.
Si esta información te ha sido de utilidad apoyame dando click en el botón 1+ del blog. Gracias.