Contenido
Documentación que reduce las preguntas a soporte
Documentación que reduce las preguntas a soporte: analiza los tickets, titula por síntoma, escribe con la tarea primero, pon la respuesta donde surge.
Soporte sigue respondiendo la misma pregunta: el dispositivo no se reconoce por USB, la rutina de calibración devuelve un error, la actualización se queda atorada en 40 %. La respuesta existe en algún lugar de un manual de 200 páginas, bajo un encabezado de función que a nadie se le ocurriría buscar. La documentación que reduce las preguntas a soporte funciona distinto. Parte de lo que la gente pregunta, usa sus palabras, la lleva rápido a un estado que funciona y vive donde aparece el problema. Esta guía explica cómo construirla, con base en la investigación sobre por qué la gente no lee los manuales y en prácticas de soporte que mantienen el conocimiento al día.
Puntos clave
- La gente evita los manuales por razones prácticas. El estudio con entrevistas de Novick y Ward de 2006 encontró que los usuarios batallaban para navegar la documentación y encontrar información con sus propios términos, y muchas veces preferían preguntarle a alguien o probar por su cuenta.
- La documentación más corta y orientada a tareas puede funcionar mejor. El “manual mínimo” de Carroll y sus colegas (1987) redujo un manual convencional a material enfocado en tareas con recuperación de errores, y quienes lo usaron aprendieron las tareas básicas más rápido.
- Knowledge-Centered Service (KCS), del Consortium for Service Innovation, captura el conocimiento durante el trabajo de soporte, registra los problemas con las palabras de quien los reporta y trata la reutilización como revisión, así que los artículos más usados son los que más rápido mejoran.
- ISO/IEC/IEEE 26514:2022 plantea la información para usuarios como algo que se diseña a partir de sus necesidades y se mantiene a lo largo de su ciclo de vida, no como algo que se escribe una vez.
- La receta práctica: analiza los tickets, titula por síntoma, escribe con la tarea primero y de forma mínima, incluye recuperación de errores, pon las respuestas en contexto y deja que soporte se encargue de las actualizaciones.
El problema: documentación organizada por producto, no por problema
La mayor parte de la documentación de producto sigue la estructura del producto: un capítulo por función, una sección por menú. Los usuarios llegan con un problema, casi siempre descrito por un síntoma o un mensaje de error, y no saben a qué función pertenece. Si el artículo que resuelve su problema está titulado por función, ni la búsqueda ni la navegación lo van a encontrar.
El segundo problema es la extensión. Secciones explicativas largas antes de los pasos, ninguna recuperación de errores y capturas de pantalla de interfaces viejas empujan al usuario hacia la opción más rápida: abrir un ticket o preguntarle a un colega.
Qué dice la investigación
Por qué la gente no lee el manual
“Why don’t people read the manual?”, de Novick y Ward (Proceedings of SIGDOC ’06), entrevistó a usuarios sobre cómo usaban los manuales impresos y la ayuda en línea. Los usuarios describieron dificultades para navegar la documentación y encontrar información con sus propios términos, y muchas veces preferían recurrir a colegas o probar por su cuenta. La columna anterior de Rettig, “Nobody reads documentation” (Communications of the ACM, 1991), planteaba algo parecido: la gente quiere seguir con su tarea, así que la documentación tiene que adaptarse a ese comportamiento en lugar de esperar que la lean primero.
Minimalismo: menos, con la tarea primero y con recuperación de errores
“The Minimal Manual”, de Carroll, Smith-Kerker, Ford y Mazur-Rimetz (Human-Computer Interaction, 1987), probó un manual drásticamente reducido para un procesador de textos, enfocado en tareas reales, en que los usuarios empezaran rápido y en ayudarles a recuperarse de errores. Quienes usaron el manual mínimo aprendieron las tareas básicas más rápido que quienes usaron el manual convencional. Los principios minimalistas que surgieron de ese trabajo, como la orientación a tareas, la brevedad, el apoyo para reconocer y corregir errores y dejar que el usuario actúe pronto, se aplican directamente a la documentación de soporte.
Captura el conocimiento donde ocurre el soporte
La KCS v6 Practices Guide del Consortium for Service Innovation describe Knowledge-Centered Service como dos ciclos. En el ciclo de resolución, el personal de soporte busca primero en la base de conocimiento, reutiliza y mejora los artículos existentes, y captura nuevos como subproducto de resolver solicitudes, registrando el problema con las palabras de quien lo reporta junto con el entorno y la solución. En el ciclo de evolución, la organización analiza los patrones de muchas solicitudes. El principio de que “reutilizar es revisar” significa que los artículos más usados son los que más se pulen.
Diseña a partir de necesidades y mantén en el tiempo
ISO/IEC/IEEE 26514:2022, Design and development of information for users, establece requisitos para la estructura, el contenido y el formato de la información para usuarios de software, y abarca determinar qué necesitan los usuarios, cómo presentarlo y cómo mantenerlo vigente. Su alcance es el software, pero el principio aplica a productos de hardware y embebidos: la documentación se diseña a partir de las necesidades de los usuarios y se mantiene a lo largo de su ciclo de vida.
Paso 1: Analiza los tickets de soporte
Exporta los tickets de los últimos meses y agrúpalos por problema de fondo. Ordena los grupos por volumen y por el tiempo que toma resolverlos. Los diez primeros son tu primera lista de pendientes de documentación.
Paso 2: Titula los artículos por síntoma o error
Usa las palabras del cliente: el texto del mensaje de error, el síntoma (“las lecturas brincan 2 °C después de encender”), el nombre del dispositivo como aparece en su sistema. Pon los códigos de error en los títulos para que la búsqueda los encuentre.
Paso 3: Escribe con la tarea primero y de forma mínima
Empieza con una respuesta de una línea y luego los pasos numerados. Limita el contexto a lo que el usuario necesita para completar la tarea, y enlaza el material explicativo para lo demás.
Paso 4: Incluye la recuperación de errores
Agrega una sección breve sobre qué hacer si los pasos no funcionan: las dos o tres causas más comunes y cómo revisar cada una. Ahí se va la mayor parte del tiempo de soporte, y casi toda la documentación la omite.
Paso 5: Pon las respuestas donde ocurren los problemas
Enlaza directamente al artículo correspondiente desde los mensajes de error, las salidas del registro (log) y las pantallas de la interfaz. Incluye en la caja una tarjeta breve de inicio rápido con un enlace a la versión en línea. Un buen artículo a tres clics del error sirve menos que uno regular enlazado desde ahí.
Paso 6: Haz que soporte forme parte del ciclo
Pide al personal de soporte que busque primero en la documentación, que enlace en cada ticket el artículo que usó y que marque o corrija los artículos que no resolvieron el problema. Los artículos que se reutilizan seguido deben revisarse seguido.
Paso 7: Indica la versión y verifica con regularidad
Di a qué versión de firmware, software o hardware aplica cada artículo y cuándo se verificó por última vez. Vuelve a verificar los artículos principales en cada lanzamiento.
Paso 8: Mide qué cambió
Mide el volumen de tickets y el tiempo de resolución de cada grupo de problemas antes y después de publicar o mejorar el artículo. Pon atención a los grupos que no bajan; quizá el artículo es difícil de encontrar o en realidad no resuelve el problema.
Hábitos de documentación que generan o reducen tickets
| Hábito | Genera tickets | Reduce tickets |
|---|---|---|
| Títulos | Por función (“Configuración USB”) | Por síntoma o error (“El dispositivo no se detecta por USB”) |
| Estructura | Primero el contexto, después los pasos | Primero la respuesta, luego los pasos y enlaces al contexto |
| Errores | No se cubren | Sección “Si sigue fallando” con las causas comunes |
| Ubicación | Solo en el manual | Enlazada desde mensajes de error, interfaz e inicio rápido |
| Formato | Solo PDF | Páginas HTML con búsqueda, PDF opcional |
| Responsable | Se escribe una vez al lanzar | Soporte la actualiza como parte de resolver tickets |
| Versiones | Sin indicar | Versión aplicable y fecha de última verificación |
Cómo aplicarlo
Si tienes una hora
Saca los diez temas de ticket más comunes del mes pasado y busca cada uno en tu documentación con las palabras del cliente. Anota cuáles no encuentras.
Si tienes un sprint
Escribe o reescribe los artículos de los cinco problemas principales, titulados por síntoma, con pasos y recuperación de errores. Si el producto lo permite, enlázalos desde los mensajes de error o las salidas de registro correspondientes.
Si quieres que dure toda la vida del producto
Adopta un proceso centrado en el conocimiento: soporte busca primero, enlaza los artículos a los tickets y corrige o marca artículos como parte de su trabajo diario, con una revisión periódica de los patrones de los tickets.
La pregunta que debes hacerte: “Si un cliente escribiera en nuestra búsqueda el error exacto que está viendo, ¿llegaría a la solución?”
Preguntas frecuentes
¿Cómo puede la documentación reducir los tickets de soporte?
Respondiendo las preguntas que la gente realmente hace, con sus palabras, donde se topa con el problema: artículos titulados por síntoma o error, pasos con la tarea primero y recuperación de errores, enlazados desde los mensajes de error y mantenidos por soporte como parte de su trabajo.
¿Qué es la documentación minimalista?
Un enfoque que surgió de la investigación sobre el manual mínimo: orientado a tareas, breve, que pone al usuario a actuar pronto y apoya el reconocimiento y la corrección de errores, en lugar de cubrir cada función en secuencia.
¿Qué es Knowledge-Centered Service?
Un conjunto de prácticas del Consortium for Service Innovation en el que el personal de soporte captura y mejora artículos de conocimiento como parte de resolver solicitudes, con las palabras de quien reporta, y la organización aprende de los patrones entre solicitudes.
¿Por qué los clientes no leen el manual?
La investigación encontró que a la gente le cuesta navegar los manuales y encontrar información con sus propios términos, y prefiere preguntar o probar. La documentación tiene que poder encontrarse por síntoma y permitir actuar rápido.
¿Cómo sé si la documentación está funcionando?
Mide el volumen de tickets y el tiempo de resolución por grupo de problemas antes y después de publicar o mejorar un artículo, y observa qué artículos enlaza más el personal de soporte.
Lecturas relacionadas: calculadoras y configuradores interactivos para ingenieros, cómo escribir artículos técnicos que los ingenieros sí creen y nota de aplicación vs tutorial vs video de producto.
Si quieres que tus preguntas de soporte más frecuentes se conviertan en documentación que las responda, es un trabajo que hacemos en AlphaCrew Studio.
Fuentes
- Novick, D. G., & Ward, K. (2006). Why don’t people read the manual? Proceedings of the 24th Annual ACM International Conference on Design of Communication (SIGDOC ’06), 11–18. https://doi.org/10.1145/1166324.1166329
- Rettig, M. (1991). Nobody reads documentation. Communications of the ACM, 34(7), 19–24. https://doi.org/10.1145/105783.105788
- Carroll, J. M., Smith-Kerker, P. L., Ford, J. R., & Mazur-Rimetz, S. A. (1987). The minimal manual. Human-Computer Interaction, 3(2), 123–153. https://doi.org/10.1207/s15327051hci0302_2
- Consortium for Service Innovation. KCS v6 Practices Guide, Section 2: The KCS Practices. https://library.serviceinnovation.org/KCS/KCS_v6/KCS_v6_Practices_Guide/030
- ISO/IEC/IEEE 26514:2022. Systems and software engineering — Design and development of information for users. https://www.iso.org/standard/77451.html
