Cómo escribir excelentes artículos

Escribir sobre los productos y funciones de Clerk es una parte crucial para hacer que las personas tengan éxito. Nuestros colegas confían en el Knowledge Center para obtener cualquier información que necesiten sobre nuestros productos cuando hablan con prospectos, clientes y socios.
Es nuestro deber sagrado (suena un coro de ángeles) mantenerlo fácil de navegar y hacer que cada artículo esté súper bien descrito para que siga siendo una herramienta esencial para cerrar la brecha entre Producto y el resto de la empresa.
Cada artículo que escribas posiblemente será leído cientos, si no miles de veces, así que debes obsesionarte con la calidad.
Writing Style #
¿Qué tan difícil puede ser escribir documentación? Anotas unas palabras que muestran a dónde ir y agregas una captura de pantalla, ¿cierto?
Bueno, sí y no. De hecho, en su mayoría no.
Cómo escribimos la documentación es tan crucial como qué escribimos. Básicamente es la UX de nuestro trabajo.
Después de todo, piensa en las principales razones por las que Apple es una de las empresas líderes en electrónica en el mundo. ¿Solo hacen teléfonos y computadoras portátiles verdad?
Sí, pero también los hacen con una calidad súper nítida y consistente que crea grupos casi religiosos de personas fieles a su ecosistema.
El diseño importa, y el diseño de un artículo del Knowledge Center es el estilo de escritura.
Esto debe ser consistentemente increíble, para que colegas y clientes estén tan religiosamente invertidos en usarlo como queremos que estén ;)
Vamos a explorar cómo puedes lograr esto.
Voice & Tone #
Al escribir para nuestros clientes, nos enfocamos en hacer las cosas claras y fáciles de entender. Nuestro objetivo es darles información útil sin confundirlos. Evitamos el lenguaje complicado y nos aseguramos de explicar cada paso necesario.
Escribimos para lectores tanto técnicos como no técnicos, así que nuestros artículos deben ser simples pero informativos para ambos tipos de lectores. Lo logramos con un gran texto y una estructura clara.
El humor es bienvenido, pero solo si encaja de forma natural. Lo más importante es ayudar a nuestros clientes sin hablarles de manera condescendiente o asumir que lo saben todo.
Hazlo Simple: Usa lenguaje claro y fácil de entender. Evita oraciones largas y confusas y palabras complicadas. Usa voz activa para que la escritura sea directa y fácil de leer.
Sé Respetuoso: Escribe de forma que trates al lector como a un igual. No asumas que ya saben las cosas. Asegúrate de proporcionar todos los detalles que necesitan, con enlaces a más información si es necesario.
Sé Claro y Útil: Concéntrate en dar información útil en vez de largas explicaciones. Guia a los lectores paso a paso, y piensa en lo que podrían buscar para que puedan encontrar fácilmente las respuestas.
Usa el Humor con Cuidado: El humor es genial si encaja de forma natural, pero nunca debe ser forzado. Si no estás seguro de que funciona, déjalo fuera. Mantén el enfoque en ser útil y claro.
Nuestro tono es informal con un gran enfoque en la claridad. El humor es bienvenido pero solo si encaja con la mentalidad que tiene un usuario al leerlo. Piensa por qué los usuarios están aquí. Si un usuario lee un artículo que explica cómo funciona Search, probablemente estén en una mentalidad de descubrimiento y el humor puede funcionar bien.
Sin embargo, si están navegando por FAQs o artículos de resolución de problemas, probablemente ya estén molestos por un problema y solo necesiten una solución clara. La mentalidad importa ;)
Cuando se use humor, hazlo geek: nos encantan las referencias a Star Wars, El Señor de los Anillos, The Matrix y otros fenómenos de la cultura geek. Suele funcionar muy bien en ejemplos de código, como verás ;)
Types of articles #
Cuando estés escribiendo, considera cuál de estos tipos resuelve mejor la necesidad del usuario.
Informational #
Explica los conceptos de un producto o función. Los lectores suelen estar en modo descubrimiento cuando leen estos y quieren entender cómo funciona. Estos artículos no incluyen pasos ni una guía exhaustiva por el backend, pero explican claramente cómo funciona cada parte.
Ejemplos:
How-Tos #
Explica cómo lograr un resultado específico. Estos requieren una guía paso a paso que explique los botones exactos que los usuarios deben pulsar y las configuraciones por las que deben pasar. Los lectores suelen estar tratando de lograr algo específico al leer estos.
Ejemplos:
FAQs / Troubleshooting #
Explica las soluciones más probables a preguntas o problemas comunes. Los lectores suelen estar frustrados en cierta medida al leer estos, porque algo no funciona como se espera. Estos deben estar claramente etiquetados con la pregunta que el lector tendrá en mente y ofrecer explicaciones claras sobre cómo resolverlo.
Nunca son artículos individuales, sino que se recopilan bajo la FAQ de un producto, función o integración específica.
Ejemplos:
Intros #
¿Notaste cómo este artículo y las secciones de Writing Style empiezan con una pequeña introducción? ¿Notaste lo que lograron?
Las intros tratan de explicar por qué algo es importante de leer. Se trata de captar la atención del lector y permitirle detectar rápidamente si ha encontrado el contenido correcto o no.
Las intros no deben ser demasiado largas, pero deben dar al lector el contexto de lo que está a punto de leer.
Incluye siempre intro al principio de los artículos y al comenzar nuevas secciones con un encabezado h2.
Title & Description #
El título de tu artículo debe ser siempre claro y conciso. Un buen título contiene máximo 3 palabras e idealmente solo 1.
Un buen título es “Omnisearch”. Una mala versión es “Our Omnisearch Feature”. Agrega demasiadas palabras innecesarias y dificulta la navegación en la estructura del menú.
Los títulos cortos funcionan bien porque son fáciles de explorar y, combinados con una estructura de menú lógica, mantenemos el Knowledge Center fácil de navegar.
Las descripciones de los artículos deben ser una sola frase que añada contexto al artículo. Ayuda a los lectores a validar si este artículo es lo que buscaban. Evita repetir el título en tu descripción; debe complementarlo.
Una buena descripción para Omnisearch es: “Una ventana de pantalla completa que sirve a tus visitantes los resultados con mayor probabilidad de convertir”. Explica claramente qué es Omnisearch, en una sola frase.
Una mala sería: “Omnisearch es una nueva función en nuestro producto de búsqueda”. Repite el nombre de la función y su lugar en nuestro catálogo, lo cual ya está claro desde el menú del Knowledge Center.
Headings #
Son cruciales para que los artículos sean fáciles de escanear y navegar. Úsalos para separar claramente las diferentes partes. Los encabezados tienen un máximo de 3 palabras.
Los encabezados son jerárquicos y siempre se usan en el siguiente orden:
- h1: Solo utilizado por el título
- h2: Sección principal
- h3: Subtítulo de h2
- h4: Subtítulo de h3
Nunca usamos encabezados menores que h4.
Todos los h2 y h3 se usan automáticamente para crear la Tabla de Contenidos.
Paragraphs #
Al escribir artículos, queremos que los lectores puedan navegar y entenderlos fácilmente. Después de todo, rara vez leerán el artículo completo, sino que lo recorrerán para encontrar las partes que necesitan.
El párrafo ideal es de entre 1 y 3 líneas. Los párrafos largos rápidamente terminan pareciendo paredes de texto. Cuando escribas, asegúrate de que sea fácil de recorrer usando saltos de línea después de al menos cada 3 líneas (al verse en un laptop de 13 pulgadas).
No es un requerimiento estricto pero sí una buena práctica general. Nuestro cerebro tiende a ver grandes bloques de texto y deduce que son difíciles de leer, aunque no lo sean.
Para visualizar la diferencia que produce, revisa la siguiente sección, donde se han eliminado los saltos de línea. Es más difícil de recorrer, ¿verdad?
Al escribir artículos, queremos que los lectores puedan navegar y entenderlos fácilmente. Después de todo, rara vez leerán el artículo completo, sino que lo recorrerán para encontrar las partes que necesitan. El párrafo ideal es de entre 1 y 3 líneas. Los párrafos largos rápidamente terminan pareciendo paredes de texto. Cuando escribas, asegúrate de que sea fácil de recorrer usando saltos de línea después de al menos cada 3 líneas (al verse en un laptop de 13 pulgadas). No es un requerimiento estricto pero sí una buena práctica general. Nuestro cerebro tiende a ver grandes bloques de texto y deduce que son difíciles de leer, aunque no lo sean. Para visualizar la diferencia que produce, revisa la sección anterior, donde se han añadido los saltos de línea. Más fácil de leer, ¿verdad?
Links #
Siempre que tenga sentido, incluye enlaces a otras partes del Knowledge Center. Ten en cuenta que el usuario debe tener todo lo que necesita en un solo artículo, así que suele valer la pena al menos resumir los puntos, antes de enlazar a otro artículo con más información.
Ejemplo:
Antes de continuar, asegúrate de crear un nuevo Element. Puedes hacerlo desde Recommendations > Elements > Create New. Lee más sobre Elements here.
Screenshots #
Usamos Brandbird para crear capturas de pantalla llamativas. Siempre incluye un fondo de buen contraste para tu captura, que no robe la atención, pero la complemente.
Las capturas de pantalla son importantes porque le muestran al lector que está en el lugar correcto en nuestro backend. Así que su propósito principal es proporcionar contexto, no mostrar cada interacción. El copywriting hace eso.
Como regla, usa como máximo una captura de pantalla contextual o video cerca del principio de un artículo. Algunos artículos no necesitan visuales. Mantén una imagen dentro del cuerpo solo cuando explique algo que el texto no puede mostrar claramente, como el diagrama de configuración de DNS.
Revisa cómo Linear usa capturas de pantalla con moderación y las complementa con buen copywriting.
Una captura de pantalla debe mostrar suficiente de la página para orientar al lector. Síguela con texto explicando los pasos a seguir o las funciones disponibles.
Por ejemplo, en vez de mostrar tres imágenes separadas para HTML, CSS y Sub-Designs, muestra una visión general útil cerca del inicio del artículo. Las anotaciones pueden aclarar un área importante.
Videos #
Usamos Loom o Tella para grabar videos. Utiliza siempre su función Embed y recuerda elegir la versión Responsive. Pueden agregarse directamente en un artículo así:
Los videos son excelentes para mostrar claramente todos los aspectos de una función o cómo hacer algo específico. Complementan bien a las guías, ya que los lectores pueden comenzar viendo el video y luego usar el artículo como referencia.
Si un video es el visual principal del artículo, colócalo cerca de la parte superior en vez de agregar una captura de pantalla contextual aparte.
Sin embargo, los videos nunca deben sustituir el texto escrito, así que todo lo que se muestre en video también debe estar escrito en texto.
Al grabar videos, recorre los puntos en orden cronológico en el mismo orden en que escribiste el artículo, para que sean fáciles de seguir.
Menu Items #
Organizamos el Knowledge Center de forma lógica y generalmente en el mismo orden en que las funciones se muestran en nuestro backend.
Solo los artículos que aplican a todos los clientes deben tener sus propias páginas. Cualquier caso particular debe agregarse bajo FAQs del aspecto relevante.
Ejemplos:
- Artículos que explican cómo funciona Omnisearch aplican a todos los clientes que usan el producto, por lo que tiene su propio artículo.
- Depurar por qué los pedidos rastreados no se muestran en el dashboard es un caso particular y se coloca en la FAQ for Any (Webshop)
Hugo #
Todo nuestro Knowledge Center está escrito usando Hugo Themes, un sistema ligero de plantillas que genera archivos HTML estáticos a partir de Markdown. Nos permite trabajar completamente en la carpeta /content y Hugo lo renderiza todo maravillosamente a través de nuestro tema.
Consulta cómo empezar con Hugo en el archivo README.md ubicado en la carpeta raíz o en el
repositorio de Github.
Folders & files #
Trabajas en la carpeta content/en y en las subcarpetas integrations & platform.
Las traducciones se gestionan con Localazy, como puedes ver en el archivo README.md en la carpeta raíz.
La estructura de archivos se parece mucho a la del menú, porque Hugo genera el menú basado en la estructura de carpetas que ves abajo.
Cada artículo está en su propia carpeta con un archivo _index.md que editas. El guion bajo debe incluirse para que Hugo entienda que esta es una página de destino.
Por defecto, el título de un artículo está definido por el nombre de la carpeta, así que elígelo cuidadosamente y sigue los ejemplos existentes. El título puede sobrescribirse en los metadatos de cada artículo.
root/
├── archetypes/
├── assets/
├── content/
│ └── en
│ └── integrations
│ └── act-on
│ └── email-recs
│ ├── _index.md
│ ├── screenshot_10535...
│ └── platform
│ └── search (the search page file)
│ └── writing (this article)
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml <-- site configuration
La URL de cada artículo se genera según la estructura de carpetas hasta la última capa, donde está el archivo _index.md. La URL del ejemplo anterior es /integrations/act-on/email-recs
Front Matter #
Esto es metadatos que puedes agregar a los artículos, como títulos, descripciones, alias (redirecciones), categorías y más.
El front matter siempre está al inicio de un artículo:
---
title: "Holy Grail"
onPageTitle: "How to find the Holy Grail"
description: "Monty Python's best movie by far"
weight: 3
aliases:
- /old/path/to/holy-grail
- /really/old/path/to/holy-grail
---
What is the airspeed velocity of an unladen swallow?...
El front matter más importante es:
- title: Un título personalizado para el artículo, que se usa para personalizar su punto de menú. Si no se incluye, se usará el nombre de la carpeta en título.
- onPageTitle: Un título que solo se muestra en la página del artículo, no en el menú. Es útil para SEO donde el título de la página podría ser “How Product Logics Work”, mientras que en el menú sigue figurando como “Logics”.
- description: Se muestra justo debajo del título en la página del artículo. Es obligatorio, pues da un contexto valioso al lector.
- weight: La posición del artículo en el menú. Cuanto menor el número, más arriba aparece en el menú.
- aliases: URLs antiguas donde ha estado el artículo. Hugo las usa para redirigir a esta página y evitar errores 404. Si alguna vez cambias el nombre de la carpeta de un artículo, tendrás que agregar su URL anterior como alias aquí. Pero en general, no cambies los nombres de carpeta. Usa title en su lugar.
Markdown #
Un gran lenguaje de marcado que te permite centrarte totalmente en el contenido, en vez de luchar también con HTML y CSS.
Los archivos Markdown se traducen a HTML que luego se muestra al cliente.
Es súper intuitivo de usar. Si alguna vez necesitas un resumen, revisa el sitio oficial.
A continuación tienes las reglas de sintaxis más comunes que necesitas.
Headers #
Pueden añadirse usando un número de # seguido del texto del encabezado.
El número de hashtags decide el encabezado:
h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax
Paragraphs #
Cualquier texto en la misma línea o en la siguiente se muestra como un solo párrafo. Al agregar 1 línea de espacio entre líneas se separan los párrafos:
Todo el texto aquí es un párrafo.
Incluso el texto aquí estará en la misma línea que el de arriba.
El texto aquí tiene su propio párrafo.
Links & Anchors #
Puedes agregarlos simplemente resaltando el texto que quieres convertir en enlace y rodeándolo con corchetes seguido de paréntesis con el enlace.
... read more about [Content here](/platform/elements/settings/)
Al referenciar artículos en el Knowledge Center, solo necesitas incluir la ruta relativa como en el ejemplo. Para referencias externas, incluye la URL completa.
Puedes usar anclas para enviar a los lectores a partes específicas de artículos largos, usando # seguido del ID del encabezado en la referencia.
El ID es una versión “sanitizada” del nombre. Por ejemplo, el encabezado “For Developers” será for-developers.
Esto se puede usar para referenciar encabezados dentro del propio artículo, o para referenciar otros artículos incluyendo su ruta relativa:
Check the [For Developers](#for-developers) section further down.
Check [Common sync errors for Magento2 here](/integrations/magento-2/faq/#common-sync-issues).
Images #
Usamos un shortcode personalizado para mostrar capturas de pantalla en los artículos.
Debes exportar siempre las imágenes como .webp desde
Brandbird para mantener alta calidad y bajo tamaño.
Las imágenes se guardan en la misma carpeta donde está tu _index.md para mantenerlas organizadas con el artículo.
La sintaxis del shortcode es:
{{< image "IMAGE_ALT" "FILENAME.webp" >}}
Siempre escribe un texto alternativo para la imagen, para que los motores de búsqueda entiendan lo que muestra.
Automatic Backgrounds #
Las imágenes obtienen automáticamente un fondo decorativo aplicado. Esto crea un efecto flotante con una sombra sutil, haciendo las capturas más atractivas visualmente.
Si tu imagen ya tiene un fondo agregado (por ejemplo, desde Brandbird), puedes desactivar el fondo automático agregando "no-background" como tercer parámetro:
{{< image "IMAGE_ALT" "FILENAME.webp" "no-background" >}}
Usa "no-background" cuando tu screenshot ya incluye su propio fondo o borde.
UI references #
El Knowledge Center se traduce automáticamente, así que para evitar traducir los nombres de los menús, utilizamos un shortcode específico para referenciar nuestra interfaz de usuario.
La sintaxis es:
{{< uiref "Search > Designs > New Design > Omnisearch" >}}
Si necesitas añadir una UI reference en un header, la sintaxis es un poco diferente, porque Hugo renderiza los encabezados de manera distinta al resto del texto:
{{% uiref "Search > Designs > New Design > Omnisearch" %}}
La salida de esto se mostrará como texto en negrita que se mantiene igual a través de las traducciones: Search > Designs > New Design > Omnisearch
Callouts #
Estas son cajas con color que pueden usarse para resaltar puntos importantes. Deben usarse con moderación, y solo cuando algo es especialmente importante.
También significa que cualquier artículo individual generalmente no debe contener más de 1 de cada una, ya que de lo contrario complican demasiado el artículo.
La sintaxis es:
{{< hint info|warning|danger >}}
**Something**: To be aware of.
{{< /hint >}}
Hay tres tipos de callouts:
Info sobre algo bueno de saber, como nuestra sugerencia para una plantilla inicial.
Warning sobre algo que podría causar un problema, como olvidar guardar antes de salir de una página.
Danger sobre algo que podría romper toda una configuración, como actualizar una extensión sin primero crear un respaldo.
Úsalos solo cuando sea realmente necesario, y según la gravedad de lo que explican.
Code blocks #
Estos vienen en dos variaciones: en línea y en bloque.
Un bloque de código en línea se crea usando dos acentos invertidos `como esto`.
Los bloques completos de código se crean rodeando el código con 3 acentos al inicio y al final, y agregando el lenguaje de código:
console.log("What an awesome code example!");
Start writing #
¡Ahora estás listo para comenzar a escribir contenido de clase mundial!
Hay mucho para digerir en este artículo, y probablemente no recuerdes ni la mitad mañana. Toma un descanso, come algo, y vuelve a leerlo.
Luego busca un artículo en el Knowledge Center que creas que podría mejorar, y réescribelo siguiendo estas pautas. Mantén esta guía abierta a la hora de escribir, para poder consultarla.
Cuando hayas hecho lo mejor posible, pide retroalimentación a un colega; no tiene que tomar más de 10 minutos y ellos podrán detectar aspectos que quizás no hayas notado.
Todos caemos en visión de túnel al escribir, así que la retroalimentación es clave para redactar el mejor contenido posible.
¡Feliz escritura!
Esta página ha sido traducida por una IA útil, por lo que puede contener errores de idioma. Muchas gracias por su comprensión.