Por qué es difícil documentar errores

Documentar errores de software es una labor compleja. Los departamentos de soporte reclaman una gestión ágil y precisa de esta información que no siempre encaja bien con los flujos establecidos en otras tareas documentales. En este artículo expongo por qué los errores requieren un tratamiento diferenciado y propongo algunas ideas para mejorar su gestión documental.

El problema con los errores

El desarrollo de cualquier aplicación va necesariamente ligado a la aparición de errores. Cuando el número de posibles errores es pequeño -como ocurre, por ejemplo, con el software incorporado en muchos electrodomésticos modernos- su tratamiento se reduce a un breve apartado de resolución de problemas en la guía del usuario. En productos de software más complejos, la posibilidad de encontrar errores aumenta considerablemente. En su libro Code Complete, Steve McConnell, estima que la media de errores en la industria es de entre 15 y 50 errores por cada 1000 líneas de código. Cualquiera que sea la cifra final, puede llegar a ser muy alta si consideramos la extensión en líneas de código de muchos programas.

Tratar estos errores resulta complejo porque, como veremos más adelante, la naturaleza de este tipo de información es particular. Cuando el número de errores conocidos es pequeño, los redactores técnicos creamos una sección dedicada a la resolución de problemas en el propio manual del producto, o advertimos de la ocurrencia de problemas en forma de notas de texto. Pero el alcance de este planteamiento es limitado. Es, además, una solución que no contenta a nadie: los técnicos no tienen una forma directa de buscar esta información y los autores entendemos que funcionalidades y errores deben de ocupar sitios distintos en la documentación. Es por ello que muchos fabricantes de software diferencian entre funcionalidades y errores en su documentación. Vemos un ejemplo de ello en el área de soporte del fabricante Red Hat, donde estas dos áreas están claramente diferenciadas:

Otro ejemplo lo tenemos en la documentación de Microsoft, donde los contenidos de soporte (support) y funcionalidad de producto (library) son independientes:

Pero, ¿por qué resulta necesaria esta división?

Funcionalidades y errores

Hay 2 razones fundamentales que explican la separación entre la documentación de funcionalidades de producto y errores.

1. El origen y tratamiento de la información es distinto

Cuando describimos el funcionamiento de un software, los redactores técnicos lo hacemos en colaboración con el especialista (habitualmente un desarrollador o analista). La información facilitada por esta figura, junto con la documentación interna del producto (casos de uso, especificaciones de producto, wireframes, etc.) son la materia prima del artículo técnico. Nuestra función como redactores es destilar toda esta información y trasladarla a la documentación del producto de una manera ordenada.

Sin embargo, en el tratamiento de errores, el origen de la información reside en la figura del especialista de soporte. Él es -después del cliente- el primero en detectar y evaluar la gravedad del problema, y es también el primero en registrar los detalles del error en la herramienta de gestión de casos (en síntesis, una base de datos con los errores de producto reportados). A diferencia de lo que sucede con la documentación del producto, esta información no se encuentra ordenada, y puede ser difícil de encontrar por otros especialistas que trabajan con la misma herramienta. Solo la información de algunos de estos errores llega a la documentación final del producto como boletines de seguridad o artículos de soporte.

2. Los tiempos de publicación son distintos

La documentación de funcionalidades sigue un proceso de desarrollo constante, pero que viene pautado por la publicación de cada nueva versión del producto. Por el contrario, los errores se producen de forma intermitente durante todo el ciclo de vida del software. La información de soporte, por su propia naturaleza, requiere de un tratamiento ágil que le permita llegar al mayor número de especialistas de soporte posible. Esta diferencia en los ritmos de publicación explica también por qué funcionalidades y errores ocupan lugares distintos en la documentación del producto.

La siguiente tabla resume las diferencias entre uno y otro tipo de información:

Tratamiento de errores

Considerando estas diferencias ¿cómo podemos mejorar la gestión de errores en documentación? Propongo aquí dos ideas básicas.

1. Vincular el tratamiento de errores y funcionalidades

Salvo excepciones, son pocos los errores reportados que llegan a la documentación de usuario. En algunos casos, las herramientas de soporte no permiten extraer y analizar la información de una forma sencilla. En otros, no existen los flujos de trabajo para explotarla eficientemente. Este hecho resulta paradójico si pensamos en el valor que tiene esta información.

Sea cual sea la aplicación para la gestión de casos, debe permitir hacer búsquedas e, idealmente, puntuar (por ejemplo, a modo de like/dislike) el valor que cada caso tratado aporta para resolver un problema similar. El redactor técnico podrá así identificar los casos más consultados o mejor valorados internamente e incorporarlos a la documentación final del producto, que es ya accesible al usuario final. Los casos más críticos se publicarán como boletines de seguridad, mientras que los más populares se integrarán en área de soporte de la documentación (normalmente, en la base de datos de conocimiento o knowledge base).

Por último, la herramienta de gestión de casos usada por el especialista debe permitir realizar búsquedas en diferentes bases de datos y presentar un resultado unificado. Esto es esencial en grandes entornos, donde es común que cada área de soporte o país mantenga su propia solución.

La propuesta es, en definitiva, romper los silos de información y establecer flujos que permitan al redactor técnico descubrir los errores más comunes e incorporarlos, ya de una forma ordenada, a la documentación del producto.

2. Facilitar la creación de contenido de soporte

También se puede promover el desarrollo de nuevo contenido de soporte mediante plantillas de documento que el técnico pueda usar de forma sencilla. Elaborar estas plantillas no es complejo porque los artículos de soporte se ajustan a un patrón muy sencillo (normalmente Síntomas-Causa-Resolución). Los especialistas suelen agradecer estas iniciativas. Si el área de soporte puede generar la información en un formato predefinido, nuestra labor revisando, adaptando o traduciendo esa información será mucho más sencilla.

Desde hace varios años, Microsoft permite crear artículos en su Knowledge Base a cualquier especialista de soporte de la compañía. Este tipo de artículos, que pasan por un proceso de revisión interna antes de su publicación, abundan en la web del fabricante bajo el epígrafe de FAST PUBLISH (del inglés, publicación rápida):

Saber cómo tratar y gestionar la información de errores resulta más sencillo si entendemos las particularidades de esta información. Hemos visto que estas particularidades requieren de un tratamiento diferenciado pero no aislado. Bajo este escenario, los redactores técnicos debemos poner en marcha iniciativas que permitan mejorar el intercambio de información con el área de soporte.

El manual no es un hotfix

La documentación de software es un recurso esencial para el usuario -tanto más cuanto mayor es la complejidad de ese software-, pero que el propio usuario entiende como su último recurso. Desde esta observación resulta fácil comprender por qué la solución a los errores de un producto de software tienen que darse en el propio producto y no en su documentación.

La escritura no puede solucionar el mal diseño

En su artículo Writing can’t fix bad design (La escritura no puede solucionar el mal diseño), Beth Aitman muestra el ejemplo de una puerta automática con un mecanismo de cierre tan confuso que se acompaña de instrucciones para su manejo. La autora utiliza este ejemplo para explicar por qué cuando el diseño de un producto no es acertado la solución no es explicar cómo usarlo. La solución es arreglar el diseño. Basta con prestar un poco de atención a nuestro alrededor para descubrir casos similares donde el diseño enrevesado de un objeto se intenta solucionar arrojando información al usuario. Desde parquímetros con un largo listado de instrucciones de uso hasta puertas donde nunca parece estar claro el sentido de giro, el mundo está lleno de ejemplos de mal diseño.


No solo coincido plenamente con el análisis de la autora, sino que además creo que el mismo argumento se puede trasladar fácilmente a un producto de software y a los errores que se derivan de su desarrollo. Si exceptuamos los problemas graves (por ejemplo, de seguridad) donde la velocidad para informar a los usuarios es crucial, dar solución a un problema con un producto en un documento no es una buena opción.

Y no hablamos solo de errores en el código, que afectan al funcionamiento del programa, sino también de aquellos que afectan a su uso. Porque una usabilidad mediocre quizá no nos impida continuar con nuestra tarea, pero puede dificultarnos innecesariamente la misma, como ocurre cuando la disposición de botones en una interfaz no sigue un orden lógico y nos obliga a pararnos para entender su funcionamiento. Esto es lo que en desarrollo de software se ha dado en llamar error estético -un nombre desafortunado, porque reduce la usabilidad a un aspecto puramente ornamental.

La gente lee novelas

La gente lee novelas. No lee documentación. -Mark Baker
En el momento de utilizar un programa de software por primera vez, el usuario no recurre a la documentación, sino que intenta descubrir el funcionamiento del mismo basándose en su experiencia previa con programas similares y en las indicaciones que le da la interfaz. Normalmente, el usuario solo recurre a la documentación en dos situaciones: cuando encuentra un error o cuando no es capaz de completar una tarea. Para el usuario la documentación es un recurso necesario, pero es siempre su último recurso.

Si entendemos esta idea de último recurso, no nos costará entender por qué el manual no es el lugar indicado para resolver errores de software o de diseño. Si una interfaz no es intuitiva y dificulta completar una tarea, añadir una explicación al manual es una solución, pero no satisface las necesidades del usuario y lo que es peor, disminuye su percepción sobre la calidad del producto. Cubrir las deficiencias de un programa en el manual puede parecer inicialmente una solución más rápida y económica que desarrollar un parche (hotfix), pero a la larga puede salir cara.

Por qué documentar

Si un buen diseño simplifica el uso de un software cabe preguntarse, ¿sigue siendo necesario acompañarlo de un manual? Invertir en la usabilidad de una aplicación no solo incide positivamente en su calidad final, además reduce la dependencia del usuario en el manual. Pero a partir de un determinado nivel de complejidad, consultar la documentación resulta inevitable. En aplicaciones como las que tenemos instaladas en nuestros teléfonos móviles no se espera que hagamos uso de un manual de instrucciones. Son aplicaciones sencillas que cumplen una única finalidad y donde las instrucciones se limitan a una pequeña introducción durante el primer uso o consejos (tooltips) para familiarizarnos con los controles en pantalla.


Pero en el mundo fuera de nuestros teléfonos no todo resulta tan sencillo. Pensemos por un momento en un paquete de software de ofimática o de diseño gráfico. Estas aplicaciones no solo son más complejas de usar, también más complejas de desarrollar, aumentando la posibilidad de encontrarnos con errores. Y es que todos entendemos que no es lo mismo el mecanismo de apertura de la puerta de casa que de la compuerta de un avión -la del avión es más compleja y viene acompañada de instrucciones.

En otros casos la documentación es fundamental para explicar no tanto cómo funciona una aplicación, sino cuál es el conjunto de tareas que debemos completar en ella. Una cosa es que un programa de software sea fácil de usar y nos permita realizar las tareas sin demasiadas complicaciones y otra muy distinta que entendamos qué tareas se espera que realicemos y en qué orden. La documentación tiene un papel esencial explicando procesos, y no solo interfaces

Si los fabricantes de software quieren evitar la frustración de sus usuarios es imprescindible que dediquen recursos a mejorar la usabilidad y reducir los errores. Pero cuando los errores -inevitablemente- aparecen, es necesario solucionarlos en el producto, y no en el manual. Porque el usuario no quiere leer manuales o descifrar interfaces, quiere completar su tarea.