Cómo escribir artículos de centro de ayuda que la gente realmente use

por Fraser Hardy

Una página de centro de ayuda con una barra de búsqueda, el título de un artículo basado en una tarea, pasos numerados y una captura de pantalla del producto incrustada

Alguien escribe «exportar facturas» en el buscador de tu centro de ayuda. Obtiene tres resultados: «Resumen de facturación», «Informes» y «Primeros pasos con los datos». Ninguno dice exportar. Cierra la pestaña y te escribe un correo.

Ese es el problema de la mayoría de los artículos de centro de ayuda. Están organizados según cómo está construido el producto, no según lo que la gente intenta hacer.

Esta es la respuesta corta. Para escribir artículos de centro de ayuda que la gente use de verdad: ponle a cada uno el nombre de una sola tarea con las palabras del cliente, di en una línea qué hace, enumera todo lo que necesitan antes, da pasos numerados con una acción cada uno, añade una captura donde la gente suele perderse y termina con lo que deberían ver cuando haya funcionado. Un artículo, una tarea. Si te sorprendes escribiendo «también puedes», probablemente sea un segundo artículo.

El resto de esta entrada es el detalle: una plantilla que puedes copiar, una reescritura de antes y después, qué escribir primero y cómo evitar que todo quede obsoleto seis semanas después del lanzamiento.

¿Qué hace bueno a un artículo de la base de conocimientos?

Nadie lee la documentación de ayuda por diversión. La gente llega en mitad de una tarea, algo molesta, normalmente desde el buscador (el tuyo o el de Google) o desde un enlace que alguien de tu equipo pegó en una respuesta. Escanea. Quiere encontrar el paso 3, hacerlo e irse.

Así que un buen artículo de la base de conocimientos es el que permite a una persona que escanea, algo molesta, terminar su tarea sin leer nada dos veces. En la práctica, eso significa:

El marco Diátaxis divide la documentación en tutoriales, guías prácticas, referencia y explicación. La mayoría de los artículos de centro de ayuda deberían ser guías prácticas. El error habitual es mezclar los cuatro tipos en una sola página, de modo que quien busca el paso 4 tiene que atravesar tres párrafos sobre por qué existe la función.

Una plantilla de artículo de centro de ayuda que puedes copiar

Anatomía anotada de un artículo de centro de ayuda: título de la tarea, introducción breve, recuadro «Antes de empezar», pasos numerados, una captura de pantalla, qué ocurre después y una sección de resolución de problemas

Esta es la plantilla desde la que empezaría cada artículo de tarea. Funciona en Zendesk, Intercom, Help Scout, GitBook o una carpeta de archivos Markdown en tu repositorio.

# [Verb] [the thing]
<!-- e.g. "Export your invoices to CSV" -->

[One or two sentences: what this does and when you'd want it.
Mention the plan or role if it's restricted.]

**Before you start**
- You need [role or permission], e.g. Admin or Owner
- [Anything to have ready: a file, an API key, a connected account]

## Steps

1. Go to **[Page name]** in the left sidebar.
2. Click **[Exact button label]**.
3. In **[Field name]**, enter [what, with an example value].
4. Click **[Confirm button label]**.

<!-- Screenshot of the step where people get stuck.
     Crop to the relevant area, highlight the target. -->

## What happens next

[What they'll see when it worked. How long it takes.
Who gets notified.]

## If it didn't work

- **[Symptom in the customer's words]**: [cause and fix]
- **[Second most common symptom]**: [cause and fix]

## Related

- [The task people usually do next]
- [The reverse task, e.g. "Remove a teammate"]

Unas notas para usarla.

La introducción no es un discurso de ventas. «Nuestra potente función de exportación te da control total de tus datos» no le dice nada al lector. «Descarga todas las facturas de un intervalo de fechas como un archivo CSV que puedes abrir en Excel o en Google Sheets» le dice si está en la página correcta.

«Antes de empezar» evita la mayoría de los tickets. El fallo clásico: alguien sigue seis pasos y descubre en el séptimo que solo los administradores pueden hacerlo. Pon los permisos y los límites del plan arriba, no en una nota al final.

«Si no funcionó» debería salir de tickets reales. No inventes la resolución de problemas. Repasa el último mes de correos de soporte y anota en qué se atascó realmente la gente. Dos o tres puntos bastan. Si quieres una forma repetible de hacerlo, hemos escrito una guía aparte sobre cómo convertir tickets de soporte en artículos de ayuda.

Antes y después: reescribir un artículo de ayuda típico

Comparación de antes y después: un artículo con nombre de función y un muro de texto, reescrito como un artículo con nombre de tarea, pasos numerados y un resultado claro

Este es el tipo de artículo que se escribe la semana en que se lanza una función. El producto es inventado, el patrón no.

Gestión de equipos

Nuestra función de Gestión de equipos facilita la colaboración. Desde el área de Ajustes puedes gestionar tu equipo, incluido añadir nuevos miembros mediante la pestaña Miembros, donde encontrarás el botón Añadir miembro, y elegir roles como Administrador, Editor o Lector, que controlan a qué puede acceder cada persona. Los usuarios invitados recibirán un correo. Ten en cuenta que solo los administradores pueden añadir miembros y que el número de puestos depende de tu plan.

Todo lo que el lector necesita está ahí. Pero en el orden equivocado, bajo un título que nadie busca, y con la salvedad de los permisos en la última frase.

Esta es la reescritura:

Invitar a un compañero

Añade a alguien a tu espacio de trabajo para que pueda ver y editar proyectos.

Antes de empezar: necesitas ser administrador. Cada persona ocupa un puesto de tu plan. Puedes ver cuántos te quedan en Ajustes > Facturación.

  1. Ve a Ajustes > Miembros.
  2. Haz clic en Añadir miembro.
  3. Introduce su dirección de correo.
  4. Elige un rol: Administrador, Editor o Lector.
  5. Haz clic en Enviar invitación.

Qué ocurre después: recibe una invitación por correo. Hasta que la acepte, aparece en la lista de Miembros con una insignia de Pendiente.

Si no funcionó: si Añadir miembro aparece en gris, has usado todos tus puestos. Elimina a alguien o añade puestos en Ajustes > Facturación.

Los mismos datos, más o menos la misma extensión. Pero el título coincide con lo que la gente escribe, la salvedad va al principio, cada paso es una sola acción y el lector sabe cuándo ha terminado. Las explicaciones de los roles pasaron a un artículo breve propio («Qué puede hacer cada rol»), enlazado desde el paso 4.

¿Qué extensión debería tener un artículo de centro de ayuda?

Lo que dure la tarea y ni una palabra más. Como regla orientativa, una guía práctica de una sola tarea ronda entre 150 y 500 palabras. Si te pasas de largo, comprueba si has pegado dos tareas o si te has desviado a explicar la filosofía de la función.

La excepción son las guías de configuración, cosas como «Conecta tu tienda de Shopify», donde de verdad hay una docena de pasos repartidos entre dos sistemas. Pueden ser largas, siempre que las dividas en secciones H2 a las que la gente pueda saltar.

Dónde ayudan las capturas de pantalla y dónde perjudican

Las capturas son lo que más notan los lectores y lo que menos mantienen los equipos.

Usa una donde la interfaz sea ambigua: una página de ajustes abarrotada, un modal con seis campos, un botón que no está donde la gente espera. Omítelas para «haz clic en Guardar». Recorta ajustado a la zona que importa y resalta el elemento clave si la pantalla está cargada.

La pega es que cada captura es una promesa de que la interfaz sigue viéndose así. Mueve un menú y tendrás decenas de artículos mostrando en silencio a los clientes una pantalla que ya no existe. Ese es el principal argumento para automatizarlas en lugar de hacerlas a mano. Comparamos las opciones (scripts de Playwright, grabadores de pantalla, herramientas que las capturan por ti) en cómo crear capturas de pantalla de producto automáticamente.

Un artículo de centro de ayuda publicado con el título de una tarea, una introducción de una línea y una captura de pantalla incrustada de la pantalla exacta que tiene delante el lector

Qué escribir primero

Si partes de cero, no intentes documentar todas las funciones. Escribe en este orden:

  1. Los primeros quince minutos. El registro, el primer paso de configuración, el primer momento de «ah, esto es útil». Todos los usuarios nuevos lo leen.
  2. Tus principales preguntas de soporte. Repasa tu bandeja de entrada. Todo lo que hayas respondido tres veces este mes merece un artículo.
  3. Todo lo que implique dinero o datos. Cambios de facturación, cancelar, eliminar, exportar. Aquí la gente está nerviosa y quiere certezas, no un párrafo vago.
  4. Integraciones. Conectar cuentas de terceros es donde la gente se atasca en pantallas que no controlas.
  5. Todo lo demás, más o menos por orden de la frecuencia con que la gente se topa con ello.

Agrúpalos en un puñado de colecciones con los nombres que usan los clientes: «Primeros pasos», «Facturación y cuenta», «Cómo usar [tu función principal]», «Integraciones», «Resolución de problemas». Evita colecciones que reflejen la estructura de tus equipos internos.

El árbol de contenido de un centro de ayuda agrupado en colecciones como Primeros pasos y Mejora las respuestas, cada una con artículos breves nombrados por tarea

Escribir documentación de ayuda: pequeños hábitos que suman

La guía de estilo de documentación para desarrolladores de Google está pensada para documentación técnica, pero la mayoría de sus consejos sobre claridad y voz sirven igual de bien para la ayuda de cara al cliente.

Lo que nadie planifica: mantener los artículos al día

Escribir el artículo es lo fácil. Lo difícil es que tu producto cambia cada semana y tu centro de ayuda no.

Sea cual sea la herramienta que uses, ayudan algunas cosas:

Lo tratamos a fondo en cómo mantener la documentación al día, incluido cómo vincular la revisión de la documentación a tu proceso de lanzamiento. Y si publicas notas de la versión, se aplica la misma disciplina: consulta cómo escribir un registro de cambios que los clientes lean de verdad.

Dónde encaja Ellie Docs

Aviso: nosotros construimos una herramienta para esto. Ellie Docs se conecta a tu repositorio de GitHub, lee el código para deducir tus funciones y pantallas de cara al usuario y redacta un centro de ayuda completo. Ejecuta tu app en un entorno aislado, captura pantallas reales del producto con la sesión iniciada y las coloca en los artículos.

El editor de artículos de Ellie Docs mostrando un artículo de ayuda redactado con una captura de pantalla del producto tomada automáticamente y las funciones en las que se basa el artículo

La parte que más me importa es el mantenimiento. Cuando se fusiona un PR, Ellie comprueba qué artículos afecta el cambio y propone ediciones como un diff que aceptas o descartas. Nada se publica por sí solo. Sigues decidiendo tú qué leen los clientes; simplemente dejas de enterarte por un ticket de soporte de que el paso 6 lleva un mes mal.

Si ya tienes un centro de ayuda, importa tus artículos existentes como borradores para que no empieces de cero. Hay un plan gratuito, sin necesidad de tarjeta.

Y si prefieres hacerlo todo a mano, la plantilla de arriba funciona perfectamente por sí sola.

Algunas preguntas habituales

¿Cuál es la diferencia entre un centro de ayuda y una base de conocimientos? No mucha, en la práctica. «Base de conocimientos» suele referirse al conjunto de artículos y «centro de ayuda» al sitio de cara al cliente con búsqueda y navegación por encima. La mayoría de las herramientas usan los términos indistintamente.

¿Quién debería escribir los artículos de ayuda: soporte, producto o ingeniería? Quien esté más cerca de las preguntas. Soporte sabe qué confunde a la gente, ingeniería sabe qué ha cambiado. Una organización que funciona bien es que soporte sea responsable del centro de ayuda y que los ingenieros señalen en sus PR los artículos afectados.

¿Quieres un primer borrador de tu centro de ayuda escrito a partir de tu propia base de código? Prueba Ellie Docs gratis y mira qué produce a partir de tu repositorio.