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.

Trabajar con referencias externas en documentación técnica

Nuestra labor como redactores técnicos es proporcionar información fiable, adaptada y relevante, pero también facilitar el acceso a otra información cuando la nuestra resulta insuficiente. Utilizar referencias a otras fuentes de forma adecuada requiere un estudio que es anterior al desarrollo del contenido.

Las referencias externas se definen como enlaces en nuestro contenido a otro contenido fuera de nuestro control. Se incluye también aquí la información tomada de otro documento e incluida en el nuestro, aunque no vaya acompañada de un enlace o URL. Las referencias internas, por el contrario, son aquellas que enlazan con contenido sobre el que sí mantenemos un control. En documentación técnica, estas referencias son normalmente enlaces a páginas web o artículos y, en menor medida, referencias bibliográficas como las que suelen encontrarse en artículos científicos.

Si trabajamos con un manual pequeño, incluir y actualizar referencias no debería suponer un gran problema. En manuales extensos, por el contrario, la gestión puede llegar a ser compleja y muy costosa en tiempo. Esta circunstancia hace necesario planificar cada artículo por adelantado, estableciendo qué contenido externo es necesario y la mejor manera de incorporarlo a nuestro texto. A continuación se discuten algunas recomendaciones para trabajar con la información de otros manuales en nuestra documentación.

Información y acción

El contenido de un texto técnico se puede sintetizar en la suma de información y acción. La información proporciona el contexto para entender una tarea, mientras que la acción describe la tarea en sí. Información y acción son elementos complementarios -aunque como usuarios frecuentemente empleamos solo de uno de ellos- y las características de uno y otro son relevantes en el tratamiento de referencias.

Tengamos en cuenta que al buscar información sobre una materia en particular, normalmente lo hacemos moviéndonos -saltando- de un contenido a otro sin dar demasiada importancia a este proceso. Pensemos por un momento en cómo usamos Wikipedia, donde saltamos de un artículo a otro buscando y complementando la información de interés. Por el contrario, cuando realizamos una tarea, esperamos que la información que se nos presenta sea suficiente para completarla sin necesidad de recurrir a otra fuente. En la búsqueda de información nuestra atención sigue un patrón (aparentemente) aleatorio, mientras que en la realización de tareas sigue un patrón lineal.

Teniendo esto en cuenta, si la referencia que vamos a añadir es informativa, conviene enlazar a ella en lugar de añadirla directamente en nuestro documento. Por el contrario, si la referencia que vamos a añadir forma parte de una acción, es más efectivo incluirla directamente en nuestro documento.

Usar elementos o etiquetas identificativas

A medida que el número de reseñas en nuestro texto aumenta, resulta más necesario llevar un registro de las mismas. Las herramientas de edición normalmente nos permiten emplear algún elemento identificativo con el que, posteriormente poder obtener un listado de todas estas referencias.

En editores avanzados tales como FrameMaker, podemos usar elementos y atributos XML para identificar y posteriormente filtrar el contenido que buscamos. En otros editores, como Microsoft Word, podemos hacer uso elementos como el texto oculto para guardar un registro de esta información que no será visible al imprimir o generar un archivo PDF. Tengamos en cuenta que no todas las referencias aparecen en forma de enlace; algunas son simplemente fragmentos de texto, listados o tablas de otros manuales. Usar una URL no siempre es la mejor opción.

Trabajar con herramientas especializadas solo cuando es imprescindible

Pero, ¿por qué no usar programas especializados para llevar un registro de las referencias? Es preciso aquí hacer una llamada de atención sobre este software: su uso no es sencillo.

Emplear o no herramientas específicas dependerá en gran medida del número de referencias que manejamos. En documentos pequeños, con un número reducido de enlaces externos, no usar ningún tipo de software puede ser la mejor opción. Citando a Mamishev:

Si el número de referencias con las que trabajas es pequeño, olvida los programas especializados y procésalas manualmente [...]. Si, por otro lado, necesitas escribir un artículo para una publicación especializada o una tesis, el tiempo invertido en aprender la técnicas de gestión de referencias se te devolverá con creces [...].

Evitar URLs a contenido externo

El problema de utilizar URLs para enlazar con contenido externo es que estas cambian con relativa facilidad. Esta circunstancia puede provocar enlaces rotos en nuestros artículos, algo que los usuarios no suelen apreciar. Resulta más óptimo indicar al lector el asunto al qué referirse, junto con una llamada genérica a la documentación en cuestión. Por ejemplo:

en lugar de:
Para más información sobre la configuración de memoria en SQL Server, revisar la siguiente información en https://msdn.microsoft.com/en-us/library/ms178067.aspx

podemos usar:
Para obtener más información sobre la configuración de memoria en SQL Server, consultar la documentación de Microsoft MSDN.

Algunos verán aquí un paso atrás en nuestra labor de facilitar la tarea al usuario. Pero eso supondría subestimar la capacidad de los motores de búsqueda para mantener la información actualizada -sin duda, mucho mejor que la nuestra- y la del usuario para encontrarla.

Incluir la información para advertir de posibles errores

Si la acción que vamos a describir afecta a un software de otro fabricante y puede ser causa de problemas, conviene añadir esta información literalmente en nuestro documento. Por ejemplo, Microsoft advierte del riesgo de modificar el Registro de Windows (un componente esencial del sistema operativo) en muchos de sus artículos técnicos. Si durante el desarrollo de una tarea requerimos del usuario una acción similar, debemos también advertir explícitamente del riesgo que conlleva.

Usar un sección Referencias al final del artículo

Una tendencia bastante común -especialmente en el caso de documentación en formato electrónico- es la de añadir al artículo una sección con otros enlaces de interés. Esta sección, que normalmente encontramos al final del texto bajo el nombre de Más información, es fácilmente reconocible por el usuario, y proporciona una vía de salida cuando nuestro contenido ya no resulta relevante o es insuficiente.

Respetar el copyright y nombrar las fuentes referenciadas

Algunos fabricantes permiten copiar libremente su información, mientras que otros limitan esta posibilidad la documentación destinada a un uso interno. Siempre es recomendable revisar la normas de copyright que el fabricante tiene para su documentación y, por supuesto, respetar estas normas.