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.