Cómo escribir excelentes artículos
Es nuestro sagrado deber (coro de ángeles suave) mantenerlo fácil de navegar y hacer que cada artículo esté súper bien descrito para que siga siendo una herramienta esencial que conecta el producto y el resto de la empresa.
Cada artículo que escribas probablemente será leído cientos, si no miles de veces, así que debes obsesionarte con la calidad.
Estilo de escritura #
¿Qué tan difícil puede ser escribir documentación? Simplemente anotas unas palabras que muestran a dónde ir y agregas una captura de pantalla, ¿verdad?
Bueno, sí y no. Mayormente no, en realidad.
Cómo escribimos la documentación es tan crucial como qué escribimos. Básicamente es la experiencia de usuario (UX) de nuestro trabajo.
Después de todo, piensa en las razones principales por las que Apple es una de las empresas líderes en electrónica en el mundo. ¿Solo hacen teléfonos y portátiles, verdad?
Sí, pero también los hacen con una calidad súper pulcra y consistente que crea grupos casi religiosos de personas que juran lealtad a su ecosistema.
El diseño importa, y el diseño de un artículo de Knowledge Center es el estilo de escritura.
Esto debe ser consistentemente increíble, para que los colegas y clientes estén tan religiosamente comprometidos con su uso como queremos ;)
Vamos a profundizar en cómo puedes lograr esto.
Voz y tono #
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 un lenguaje complicado y nos aseguramos de explicar cada paso necesario.
Escribimos para lectores técnicos y no técnicos, así que nuestros artículos deben ser simples pero informativos para ambos tipos de lectores. Hacemos esto con buen copywriting 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 con condescendencia o asumir que lo saben todo.
Hazlo simple: Usa lenguaje claro y fácil de entender. Evita frases largas, confusas y palabras complicadas. Utiliza voz activa para lograr una escritura directa y fácil de leer.
Sé respetuoso: Escribe de manera que trates al lector como tu igual. No asumas que ya saben las cosas. Asegúrate de aportar todos los detalles que necesitan, con enlaces para más información si es necesario.
Sé claro y útil: Concéntrate en dar información útil en vez de explicaciones largas. Guía a los lectores paso a paso y piensa en lo que podrían buscar, para que encuentren las respuestas fácilmente.
Usa el humor con cuidado: El humor es genial si sale natural, pero nunca debe forzarse. 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 gran enfoque en la claridad. Se anima al humor pero solo si encaja con la mentalidad que tiene el usuario cuando lo lee. Piensa por qué los usuarios están aquí. Si un usuario lee un artículo que explica cómo funciona Search, probablemente está en una mentalidad de descubrimiento y el humor puede funcionar bien.
Sin embargo, si están navegando preguntas frecuentes o artículos de resolución de problemas, probablemente ya estén frustrados por un problema, y simplemente necesitan una solución clara. La mentalidad importa ;)
Cuando uses humor, hazlo geek – Nos encantan las referencias de 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 ;)
Tipos de artículos #
Cuando estés escribiendo, considera cuál de estos tipos resuelve mejor la necesidad del usuario.
Informativo #
Explica los conceptos de un producto o función. Los lectores suelen estar en modo de descubrimiento al leer estos y quieren entender cómo funciona. Estos artículos no incluyen pasos ni una guía detallada a través del backend, pero sí explican claramente cómo funciona cada parte.
Ejemplos:
Guía paso a paso (How-Tos) #
Explica cómo lograr un resultado específico. Estos requieren una guía paso a paso explicando los botones exactos en los que los usuarios deben hacer clic y las configuraciones por las que deben pasar. Los lectores generalmente intentan lograr algo específico al leer estos artículos.
Ejemplos:
Preguntas frecuentes / Resolución de problemas #
Explica las soluciones más probables a preguntas comunes o problemas. Los lectores suelen estar frustrados en cierta medida al navegar por estos artículos, porque algo no funciona como esperaban. Deben estar claramente etiquetados con la pregunta que el lector tendrá en mente y proporcionar explicaciones claras de cómo resolverla.
Estos nunca son artículos individuales, sino que se recopilan bajo la FAQ para un producto, característica o integración específica.
Ejemplos:
Intros #
¿Notas cómo este artículo y las secciones de Estilo de Escritura comienzan con una pequeña introducción? ¿Te diste cuenta de lo que lograron?
Las introducciones tratan de explicar por qué es importante leer algo. Se trata de captar la atención del lector y permitirle identificar rápidamente si ha encontrado el contenido que buscaba.
Las introducciones no deben ser demasiado largas, pero sí deben dar a los lectores el contexto de lo que van a leer.
Incluye siempre una introducción al inicio de los artículos y al comenzar nuevas secciones con un encabezado h2.
Título y descripción #
El título de tu artículo siempre debe ser claro y conciso. Un buen título contiene máximo 3 palabras, e idealmente solo 1.
Un buen título es “Omnisearch”. Una versión mala sería “Nuestra función Omnisearch”. Añade palabras innecesarias y hace que la estructura del menú sea más difícil de navegar.
Los títulos cortos funcionan bien porque son fáciles de recorrer 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 estaban buscando. Evita repetir el título en la descripción: debe complementarlo.
Una buena descripción para Omnisearch es: “Una ventana de página completa que sirve a tus visitantes los resultados con mayor probabilidad de conversión”. Explica claramente qué es Omnisearch, en una sola frase.
Una mala sería: “Omnisearch es una función nueva de nuestro producto de búsqueda”. Repite el nombre de la función y su ubicación en nuestro catálogo, lo cual ya está claro en el menú del Knowledge Center.
Encabezados #
Son cruciales para hacer que los artículos sean fáciles de recorrer y navegar. Úsalos para separar claramente las diferentes partes. Los encabezados no deben tener más de 3 palabras.
Los encabezados son jerárquicos y siempre se usan en el siguiente orden:
- h1: Solo para 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.
Párrafos #
Al escribir artículos, queremos que los lectores puedan navegar y entenderlos fácilmente. Después de todo, raramente leerán el artículo completo, sino que lo recorrerán para encontrar las partes que necesitan.
El párrafo ideal tiene entre 1 y 3 líneas. Los párrafos más largos acaban pareciendo muros de texto. Cuando escribas, asegúrate de que sea fácil de recorrer añadiendo saltos de línea al menos cada 3 líneas (al visualizarlos en un portátil de 13 pulgadas).
No es un requisito estricto, pero sí una buena regla general. Nuestro cerebro suele ver bloques grandes de texto y deduce que son difíciles de leer, incluso si no lo son.
Para visualizar la diferencia que esto hace, revisa la sección abajo, donde se han eliminado los saltos de línea. 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, raramente leerán el artículo completo, sino que lo recorrerán para encontrar las partes que necesitan. El párrafo ideal tiene entre 1 y 3 líneas. Los párrafos más largos acaban pareciendo muros de texto. Cuando escribas, asegúrate de que sea fácil de recorrer añadiendo saltos de línea al menos cada 3 líneas (al visualizarlos en un portátil de 13 pulgadas). No es un requisito estricto, pero sí una buena regla general. Nuestro cerebro suele ver bloques grandes de texto y deduce que son difíciles de leer, incluso si no lo son. Para visualizar la diferencia que esto hace, revisa la sección arriba, donde los saltos de línea han sido añadidos. Más fácil de leer, ¿verdad?
Enlaces #
Siempre que tenga sentido, incluye enlaces a otras partes del Knowledge Center. Ten en cuenta que el usuario debe tener todo lo necesario en cualquier artículo, así que normalmente vale 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 aquí.
Capturas de pantalla #
Usamos Brandbird para crear capturas elegantes. Incluye siempre un fondo de buen contraste para tu captura, que no sobresalga pero la complemente.
Las capturas de pantalla son importantes porque muestran al lector que está en el lugar correcto en nuestro backend. Así que su principal propósito es proporcionar contexto, no mostrar cada interacción; la redacción lo hace.
Una buena regla es incluir como máximo el mismo número de imágenes que los títulos h2 y h3 que tengas. Menos también está bien; a menudo, menos es más en capturas de pantalla.
Revisa cómo Linear usa capturas muy pocas veces y emplea buena redacción para complementarlas.
Una captura de pantalla debe, en general, cubrir toda la extensión de una página, seguida de texto explicando los pasos a seguir o las funciones disponibles.
Por ejemplo, en vez de mostrar 3 imágenes diferentes para HTML, CSS y Sub-Designs por separado, una sola imagen que muestre todo en el párrafo inicial es mejor. Las anotaciones también son bienvenidas para ayudar a clarificar partes de una imagen.
Videos #
Usamos Loom o Tella para grabar videos. Utiliza las funciones Embed de cada uno y recuerda elegir siempre la versión Responsive. Puedes añadirlos directamente a 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 muy bien las guías, ya que los lectores pueden empezar viendo el video antes de usar el artículo como referencia.
Sin embargo, los videos nunca deben reemplazar el texto escrito, así que todo lo que se muestre en un video también debe estar escrito en texto.
Al grabar videos, aborda los puntos cronológicamente en el mismo orden en que redactaste el artículo, para que sean fáciles de seguir.
Elementos del menú #
Organizamos el Knowledge Center de manera lógica y generalmente en el mismo orden en que las funciones se muestran en nuestro backend.
Solo los artículos que son aplicables para todos los clientes deben tener su propia página. Cualquier caso especial debe añadirse en la sección de FAQ para ese aspecto relevante.
Ejemplos:
- Los artículos explicando cómo funciona Omnisearch son aplicables a todos los clientes que usan el producto, por lo que tiene su propio artículo.
- La solución de problemas para pedidos rastreados que no aparecen en el dashboard es un caso especial, así que se pone en la FAQ para Any (Webshop)
Hugo #
Todo nuestro Knowledge Center está desarrollado usando Hugo Themes — Un sistema de plantillas ligero que genera archivos HTML estáticos a partir de Markdown. Nos permite trabajar completamente en la carpeta /content y Hugo lo renderiza todo bellamente a través de nuestro tema.
Revisa cómo empezar con Hugo en el archivo README.md en la carpeta raíz o en el
repo de Github.
Carpetas y archivos #
Trabajas en la carpeta content/en y en las subcarpetas integrations & platform.
Las traducciones se manejan mediante Localazy tal como puedes ver en el archivo README.md en la carpeta raíz.
La estructura de archivos se parece mucho a la estructura del menú, porque Hugo genera el menú basado en la estructura de carpetas que ves a continuación.
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 es una landing page.
Por defecto, el título del 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 el front matter de cada artículo.
root/
├── archetypes/
├── assets/
├── content/
│ └── en
│ └── integrations
│ └── act-on
│ └── email-recs
│ ├── _index.md
│ ├── screenshot_10535...
│ └── platform
│ └── search (el archivo de la página search)
│ └── writing (este artículo)
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml <-- configuración del sitio
La URL de cada artículo se genera en base a la estructura de carpetas hasta la última capa, donde está el archivo _index.md. La URL para el ejemplo anterior es /integrations/act-on/email-recs
Front Matter #
Esto es metadatos que puedes añadir a los artículos, como títulos, descripciones, alias (redirecciones), categorías y más.
El front matter siempre va al inicio de un artículo:
---
title: "Holy Grail"
onPageTitle: "How to find the Holy Grail"
description: "La mejor película de Monty Python por lejos"
weight: 3
aliases:
- /old/path/to/holy-grail
- /really/old/path/to/holy-grail
---
¿Cuál es la velocidad de vuelo de una golondrina sin carga?...
El front matter más importante es:
- title: Un título personalizado para el artículo, usado para personalizar su punto de menú. Si no se incluye, se usará el nombre de la carpeta en Title Case.
- onPageTitle: Un título mostrado solo en la página del artículo, no en el menú. Es útil para SEO donde el título podría ser “How Product Logics Work”, mientras que el artículo sigue listado como “Logics” en el menú.
- description: Aparece justo bajo el título en la página del artículo. Es obligatorio, ya que da contexto valioso al lector.
- weight: La posición del artículo en el menú. Cuanto menor el número, más arriba se muestra en el menú.
- aliases: URLs antiguas donde ha estado ubicado este artículo antes. Hugo usa esto 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 añadir su URL anterior aquí como alias. Pero en general, no cambies los nombres de las carpetas. Usa title en su lugar.
Markdown #
Un gran lenguaje de marcado que te permite centrarte totalmente en el contenido, en lugar de lidiar también con HTML y CSS.
Los archivos Markdown se traducen a HTML que luego se muestra al cliente.
Es muy intuitivo de usar. Si alguna vez necesitas una referencia rápida, consulta el sitio oficial.
Abajo están las reglas de sintaxis más comunes que necesitas.
Encabezados #
Se agregan usando varios # seguidos del texto del encabezado.
El número de hashtags decide el encabezado:
h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax
Párrafos #
Cualquier texto en la misma o siguiente línea se muestra como un solo párrafo. Al agregar una línea de espacio entre líneas se separan los párrafos:
Todo el texto aquí es un solo párrafo.
Incluso el texto aquí estará en la misma línea que el de arriba.
El texto mostrado aquí tendrá su propio párrafo.
Enlaces y anclas #
Puedes añadir enlaces resaltando el texto que quieras enlazar y envolviéndolo entre corchetes seguido de paréntesis con el enlace
... lee más sobre [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 llevar 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 “limpiada” del nombre. Por ejemplo, el encabezado “For Developers” tendrá el ID for-developers.
Esto puede usarse para referenciar encabezados dentro del propio artículo o para referenciar otros artículos incluyendo también su ruta relativa:
Revisa la sección [For Developers](#for-developers) más abajo.
Revisa [Common sync errors for Magento2 here](/integrations/magento-2/faq/#common-sync-issues).
Imágenes #
Usamos un shortcode personalizado para mostrar capturas en los artículos.
Debes exportar siempre las imágenes como .webp desde
Brandbird para mantener alta la calidad y bajo el peso del archivo.
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" >}}
Escribe siempre un texto alternativo para la imagen, para que los motores de búsqueda puedan entender lo que se muestra en ellas.
Fondos automáticos #
Las imágenes obtienen automáticamente un fondo decorativo que crea un efecto flotante con una sombra sutil, haciendo las capturas visualmente más atractivas.
Si una imagen ya tiene un fondo integrado (por ejemplo de Brandbird), puedes desactivar el fondo automático añadiendo "no-background" como tercer parámetro:
{{< image "IMAGE_ALT" "FILENAME.webp" "no-background" >}}
Usa "no-background" cuando tu captura ya tenga su propio fondo o borde de estilo añadido.
Referencias de interfaz #
El Knowledge Center se traduce automáticamente, por lo que para evitar traducir los elementos del menú, usamos un shortcode especial para referenciar la interfaz de usuario.
La sintaxis es:
{{< uiref "Search > Designs > New Design > Omnisearch" >}}
Si necesitas añadir una referencia UI en un encabezado, la sintaxis es ligeramente diferente, porque Hugo renderiza los encabezados de manera diferente que el resto del texto:
{{% uiref "Search > Designs > New Design > Omnisearch" %}}
El resultado de esto se mostrará como texto en negrita que permanece igual en todas las traducciones: Search > Designs > New Design > Omnisearch
Callouts (avisos destacados) #
Estas son cajas de color que pueden usarse para resaltar puntos importantes. Deben usarse con moderación y solo cuando algo es especialmente importante.
También significa que en cualquier artículo no debería haber más de una de cada uno, ya que de lo contrario complican demasiado el artículo.
La sintaxis es:
{{< hint info|warning|danger >}}
**Algo**: A tener en cuenta.
{{< /hint >}}
Hay tres tipos de avisos:
Info sobre algo que es bueno saber, como nuestra sugerencia para una plantilla inicial.
Advertencia sobre algo que podría ser un problema, como olvidar guardar antes de salir de la página.
Peligro sobre algo que podría romper toda una configuración, como actualizar una extensión sin antes crear una copia de seguridad.
Úsalos solo cuando sea realmente necesario, y según la gravedad de lo que explican.
Bloques de código #
Vienen en dos variantes: en línea y en bloque.
Un bloque de código en línea se crea usando dos tildes invertidas `así`.
Los bloques de código completos se crean envolviendo el código entre 3 tildes invertidas al inicio y al final, y añadiendo el lenguaje para la sintaxis:
console.log("¡Qué ejemplo de código tan genial!");
Comienza a escribir #
¡Ahora estás listo para comenzar a escribir contenido de clase mundial!
Hay mucho que asimilar en este artículo, y probablemente mañana no recordarás ni la mitad. Tómate un descanso, come algo y vuelve a leerlo.
Luego encuentra un artículo en el Knowledge Center que creas que podría ser mejorado y reescríbelo siguiendo estas pautas. Mantén esta guía abierta mientras escribes, para consultarla.
Cuando hayas hecho tu mejor esfuerzo, busca retroalimentación de un colega — no tiene que tomar más de 10 minutos, y probablemente detectarán aspectos que no notaste.
Todos nos enfocamos demasiado cuando escribimos, así que la retroalimentación es crucial para escribir 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.