Cómo escribir excelentes artículos
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 potencialmente 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? Apuntas algunas palabras que muestran a dónde ir y agregas una captura de pantalla, ¿verdad?
Bueno, sí y no. En realidad, la mayoría de las veces no.
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 principales razones por las que Apple es una de las principales empresas de electrónica del mundo. ¿Solo hacen teléfonos y portátiles, verdad?
Sí, pero también los hacen con una calidad súper nítida y consistente que crea casi grupos religiosos de personas que juran por 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 tanto colegas como clientes estén tan religiosamente invertidos en usarlo como nosotros queremos que lo estén ;)
Vamos a profundizar en cómo puedes hacer 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 que cada paso necesario esté explicado.
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 hacemos a través de buenos textos y una estructura clara.
El humor es bienvenido, pero solo si encaja de forma natural. Lo más importante, queremos ayudar a nuestros clientes sin hablarles desde arriba ni asumir que lo saben todo.
Hazlo simple: Usa un lenguaje claro y fácil de entender. Evita frases largas, 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 un igual. No asumas que ya sabe cosas. Asegúrate de dar todos los detalles necesarios, con enlaces a más información si es necesario.
Sé claro y útil: Enfócate en dar información útil en vez de largas explicaciones. Guía a los lectores paso a paso y piensa en qué podrían buscar para que puedan encontrar fácilmente las respuestas.
Usa el humor con cuidado: El humor es genial si encaja de manera natural, pero nunca debe forzarse. Si no estás seguro de si 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 se fomenta pero solo si encaja con la mentalidad de 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, seguramente esté en modo 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 frustrados por un problema y simplemente necesiten una solución clara. La mentalidad importa ;)
Cuando se use humor, hazlo nerd: 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 ;)
Tipos de artículos #
Cuando escribas, considera cuál de estos tipos resuelve mejor la necesidad del usuario.
Informativos #
Explican 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 guías detalladas del backend, pero explican claramente cómo funciona cada parte.
Ejemplos:
How-Tos #
Explican cómo lograr un determinado resultado. Estos requieren una guía paso a paso explicando los botones exactos que los usuarios deben pulsar y las configuraciones que deben realizar. Los lectores suelen estar intentando lograr algo específico cuando leen estos.
Ejemplos:
FAQs / Troubleshooting #
Explican las soluciones más probables a preguntas o problemas comunes. Los lectores a menudo ya están algo frustrados al leer estos, porque algo no funciona como esperaban. Deben estar claramente etiquetados con la pregunta que el lector tiene en mente y proporcionar explicaciones claras de cómo resolverlo.
Estos nunca deben ser artículos individuales, sino que se recopilan bajo la FAQ de un producto, función o integración específica.
Ejemplos:
Intros #
¿Notas cómo este artículo y las secciones Estilo de Escritura 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 ver rápidamente si ha encontrado el contenido adecuado 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 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 debe ser siempre claro y conciso. Un buen título contiene un máximo de 3 palabras e idealmente solo 1.
Un buen título es “Omnisearch”. Una mala versión es “Nuestra función Omnisearch”. Añade demasiadas palabras innecesarias y dificulta navegar por la estructura del menú.
Los títulos cortos funcionan bien porque son fáciles de consultar, y combinados con una estructura de menú lógica, mantenemos el Knowledge Center fácil de navegar.
La descripción del artículo debe ser una frase que agregue contexto al artículo. Ayuda al lector a validar si este artículo es lo que buscaba. Evita repetir el título en tu 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 más probabilidades 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 search”. Repite el nombre de la función y su sitio en nuestro catálogo, que ya es claro en el menú del Knowledge Center.
Encabezados #
Son cruciales para que los artículos sean fáciles de hojear y navegar. Úsalos para separar claramente diferentes partes. Los encabezados son de máximo 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 más pequeños que h4.
Todos los h2 y h3 se usan automáticamente para crear la Tabla de Contenido.
Párrafos #
Al escribir artículos, queremos que los lectores puedan navegar y comprenderlos fácilmente. Al fin y al cabo, rara vez leerán el artículo completo, sino que lo hojearán para encontrar las partes que necesitan.
El párrafo ideal tiene entre 1-3 líneas. Los párrafos más largos rápidamente parecen muros de texto. Cuando escribas, asegúrate de que sea fácilmente escaneable agregando saltos de línea después de al menos cada 3 líneas (visto en un portátil de 13 pulgadas).
No es un requisito estricto pero es una buena regla general. Nuestro cerebro tiende a ver bloques grandes de texto y deducir que son difíciles de leer, aunque no lo sean.
Para visualizar la diferencia, revisa la sección de abajo, donde se han eliminado los saltos de línea. Es más difícil hojear, ¿verdad?
Al escribir artículos, queremos que los lectores puedan navegar y comprenderlos fácilmente. Al fin y al cabo, rara vez leerán el artículo completo, sino que lo hojearán para encontrar las partes que necesitan. El párrafo ideal tiene entre 1-3 líneas. Los párrafos más largos rápidamente parecen muros de texto. Cuando escribas, asegúrate de que sea fácilmente escaneable agregando saltos de línea después de al menos cada 3 líneas (visto en un portátil de 13 pulgadas). No es un requisito estricto pero es una buena regla general. Nuestro cerebro tiende a ver bloques grandes de texto y deducir que son difíciles de leer, aunque no lo sean. Para visualizar la diferencia, revisa la sección de arriba, donde los saltos de línea están agregados. 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, por lo que a menudo 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 de pantalla elegantes. Siempre incluye un fondo de buen contraste para tu captura, que no robe la atención, sino que la complemente.
Las capturas de pantalla son importantes porque muestran al lector que está en el sitio correcto de nuestro backend. Así que su objetivo principal es proporcionar contexto, no mostrar cada interacción. Eso lo hace el texto.
Una buena regla general es incluir como máximo la misma cantidad de imágenes que de encabezados h2 y h3. Menos también está bien: a menudo, menos es más respecto a capturas de pantalla.
Mira cómo Linear usa capturas con moderación y buen copy para complementarlas.
Una captura normalmente debería mostrar toda la página, seguida de texto que explique los pasos a seguir, o las funciones disponibles.
Ej. en vez de mostrar 3 imágenes diferentes para HTML, CSS y Sub-Designs por separado, es mejor una sola en el párrafo inicial que lo muestre todo. También se admiten anotaciones para ayudar a clarificar partes de una imagen.
Videos #
Usamos Loom o Tella para grabar vídeos. Usa sus funciones de Embed y recuerda siempre elegir la versión Responsive. Se pueden agregar directamente a un artículo así:
Los vídeos son geniales para mostrar claramente todos los aspectos de una función o cómo hacer algo específico. Complementan bien las guías, ya que los lectores suelen empezar viendo el vídeo antes de usar el artículo como referencia.
Sin embargo, los vídeos nunca deben reemplazar el texto escrito, así que todo lo mostrado en un vídeo también debe escribirse.
Al grabar vídeos, sigue los puntos cronológicamente en el mismo orden que escribiste el artículo, para que sean fáciles de seguir.
Ítems del menú #
Organizamos el Knowledge Center de forma lógica, y generalmente en el mismo orden en que las funciones aparecen en nuestro backend.
Solo los artículos aplicables a todos los clientes deben tener su propia página. Cualquier caso particular debe añadirse bajo la FAQ del aspecto relevante.
Ejemplos:
- Los artículos que explican cómo funciona Omnisearch son aplicables a todos los clientes que usan el producto, así que tiene su propio artículo.
- Depurar por qué los pedidos seguidos no se muestran en el dashboard es un caso particular y se ubica en la FAQ de Any (Webshop)
Hugo #
Todo nuestro Knowledge Center está escrito usando Hugo Themes, un sistema de plantillas ligero que genera archivos estáticos HTML a partir de Markdown. Nos permite trabajar enteramente en la carpeta /content y Hugo lo renderiza todo bellamente a través de nuestro tema.
Mira cómo empezar con Hugo en el archivo README.md que se encuentra en la carpeta raíz o en el
repositorio de Github.
Carpetas y archivos #
Trabajas en la carpeta content/en y en las subcarpetas integrations y 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 al menú, porque Hugo representa el menú en base a la estructura de carpetas que ves abajo.
Cada artículo está en su propia carpeta con un archivo _index.md que editas. El guión bajo debe incluirse para que Hugo entienda que es una landing page.
Por defecto, el título de un artículo lo define el nombre de la carpeta, así que elígelo cuidadosamente y sigue los ejemplos existentes. El título se puede sobrescribir en el front matter 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 <-- configuración del sitio
La URL de cada artículo se genera en función de la estructura de carpetas hasta la última capa, donde está el archivo _index.md. La URL para el ejemplo de arriba 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 en la parte superior del 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, usado para personalizar su punto en el menú. Si no se incluye, se usará el nombre de la carpeta en Title Case.
- onPageTitle: Un título que solo se muestra en la página del artículo, no en el menú. Es bueno para SEO cuando el título podría ser “How Product Logics Work”, y el artículo sigue listado como “Logics” en el menú.
- description: Mostrada justo debajo del título en la página del artículo. Es obligatoria porque da contexto valioso al lector.
- weight: Posición del artículo en el menú. Cuanto menor el número, más arriba aparecerá en el menú.
- aliases: Antiguas URLs donde antes se encontraba este artículo. Hugo usa esto para redirigir a esta página y evitar errores 404. Si cambias el nombre de la carpeta de un artículo, deberás añadir su URL anterior como alias aquí. Pero en general, no cambies los nombres de las carpetas. Usa title en su lugar.
Markdown #
Un excelente lenguaje de marcado que te permite concentrarte en el contenido, en vez de lidiar con HTML y CSS.
Los archivos Markdown se traducen a HTML, que es lo que ve el cliente.
Es muy intuitivo de usar. Si alguna vez necesitas una referencia rápida, revisa el sitio oficial.
Abajo tienes las reglas de sintaxis más comunes que necesitas.
Encabezados #
Se agregan usando un número de # seguido del texto del encabezado.
El número de almohadillas determina el encabezado:
h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax
Párrafos #
Cualquier texto en la misma línea o la siguiente se muestra como un solo párrafo. Al añadir 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í saldrá en la misma línea que el anterior.
El texto mostrado aquí tendrá su propio párrafo.
Enlaces y anclas #
Pueden añadirse simplemente destacando el texto que quieres enlazar y envolviéndolo en corchetes seguidos de paréntesis con el enlace
... lee más sobre [Content aquí](/platform/elements/settings/)
Al referenciar artículos en el Knowledge Center, solo tienes que 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 sanitizada del nombre. Por ejemplo, el encabezado “For Developers” tendrá el ID for-developers.
Esto se puede usar 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.
Mira [Common sync errors for Magento2 aquí](/integrations/magento-2/faq/#common-sync-issues).
Imágenes #
Usamos un shortcode personalizado para mostrar capturas en los artículos.
Siempre debes guardar las imágenes como .webp desde
Brandbird para mantener alta calidad y poco peso.
Las imágenes se guardan en la misma carpeta donde está tu _index.md para mantenerlas organizadas.
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 qué aparece en ellas.
Fondos automáticos #
Las imágenes reciben de forma automática un fondo decorativo. Esto crea un efecto flotante con una sombra sutil, haciendo que las capturas sean más atractivas visualmente.
Si una imagen ya tiene un fondo añadido (por ejemplo, desde 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 incluya su propio fondo o borde.
Referencias UI #
El Knowledge Center se traduce automáticamente, así que para evitar traducir elementos del menú, usamos un shortcode específico para referenciar nuestra interfaz.
La sintaxis es:
{{< uiref "Search > Designs > New Design > Omnisearch" >}}
Si necesitas agregar una referencia de UI en un encabezado, la sintaxis es ligeramente diferente, porque Hugo renderiza los encabezados de manera diferente al resto:
{{% uiref "Search > Designs > New Design > Omnisearch" %}}
El resultado se mostrará como texto en negrita que permanece igual en todas las traducciones: Search > Designs > New Design > Omnisearch
Avisos #
Son recuadros coloreados que pueden usarse para destacar puntos importantes. Deben usarse con moderación y solo cuando algo sea especialmente relevante.
También significa que cualquier artículo en general no debería contener más de 1 de cada uno, para no sobrecomplicar el artículo.
La sintaxis es:
{{< hint info|warning|danger >}}
**Algo**: A tener en cuenta.
{{< /hint >}}
Hay tres tipos de avisos:
Información sobre algo que es bueno saber, como nuestra sugerencia de plantilla inicial.
Advertencia sobre algo que podría ser un problema, como olvidar guardar antes de salir de una página.
Peligro sobre algo que podría romper toda una configuración, como actualizar una extensión sin primero crear una copia de seguridad.
Úsalos solo cuando realmente sea 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 que se crea usando dos acentos `así`.
Los bloques de código completos se crean envolviendo el código con 3 acentos al principio y final, y añadiendo el lenguaje para el resaltado:
console.log("¡Qué gran ejemplo de código!");
Empieza a escribir #
¡Ahora ya estás listo para comenzar a escribir contenido de clase mundial!
Hay mucho que asimilar en este artículo y probablemente no recuerdes ni la mitad mañana. Tómate un descanso, come algo y léelo de nuevo.
Luego, encuentra un artículo en el Knowledge Center que creas que podría mejorar y reescríbelo usando estas directrices. Mantén esta guía abierta mientras escribes para consultarla.
Cuando hayas hecho lo mejor posible, busca feedback de un compañero, no tiene que tomar más de 10 minutos y podrá detectar detalles que tal vez no percibiste.
Todos nos enfrascamos cuando escribimos, así que el feedback es esencial para crear 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.