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.