Redacción técnica

Documentación escrita desde el producto, no desde la especificación

La mayoría de la documentación mala se escribió a partir de un documento de requisitos o de la memoria de un desarrollador. Describe cómo debía funcionar la función, no la pantalla que el usuario ve realmente, con su botón renombrado y su paso de confirmación adicional. El usuario sigue el paso cuatro, no encuentra nada que coincida y abre una incidencia.

Ejecutamos cada procedimiento del producto antes de escribirlo, en una cuenta de prueba y con el rol que tendrá el lector. Cuando un paso se comporta de forma distinta a lo que espera el equipo, lo registramos, porque el trabajo de documentación saca a la luz fallos que nadie había reportado. Esa lista suele resultar tan valiosa como la documentación.

Separar la tarea de la explicación

Un usuario que intenta exportar una factura no quiere primero tres párrafos sobre el modelo de facturación. Un usuario que intenta entender el modelo de facturación no quiere una lista numerada de clics. Mezclar ambas cosas en un mismo artículo hace que las dos sean más difíciles de encontrar y más lentas de leer.

Dividimos el contenido en tareas (cómo hacer una cosa), conceptos (cómo funciona algo y por qué) y referencia (ajustes, campos, límites, códigos de error). Cada tipo tiene su propia plantilla, así las páginas se mantienen coherentes después del traspaso y su equipo añade el artículo número cuarenta.

La lista de terminología es lo que mantiene el conjunto coherente con el tiempo. Si la interfaz dice «espacio de trabajo», la documentación nunca dice «proyecto» o «cuenta» para lo mismo. Es un documento pequeño que evita la mayor parte de la confusión que reportan los usuarios.

• Artículos de tareas: un objetivo, pasos numerados, el resultado que el usuario debe ver
• Artículos conceptuales: el modelo detrás de una función, con un diagrama cuando ayuda
• Páginas de referencia: cada campo, ajuste y límite, en una tabla fácil de consultar
• Resolución de problemas: el mensaje de error tal cual aparece, su causa y la solución