Cómo escribir grandes artículos
Es nuestro deber sagrado (coro de ángeles tenue) 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 el Producto y el resto de la empresa.
Cada artículo que escribas será potencialmente 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? ¿Escribes algunas palabras que muestran a dónde ir y agregas una captura de pantalla, verdad?
Bueno, sí y no. Principalmente no, de hecho.
Cómo escribimos documentación es tan crucial como qué escribimos. Es básicamente la experiencia del usuario de nuestro trabajo.
Después de todo, piensa en las principales razones por las que Apple es una de las empresas de electrónica líderes en el mundo. ¿Solo fabrican teléfonos y laptops, verdad?
Sí, pero también los fabrican con una calidad súper nítida y consistente que crea casi grupos religiosos de personas que juran lealtad a su ecosistema.
El diseño importa, y el diseño de un artículo del Centro de Conocimiento es el estilo de escritura.
Esto debe ser consistentemente asombroso, para que colegas y clientes estén tan religiosamente interesados en usarlo, como 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 el lenguaje complicado y nos aseguramos de que cada paso necesario esté explicado.
Escribimos tanto para lectores técnicos como no técnicos, así que nuestros artículos necesitan ser simples pero informativos para ambos tipos de lectores. Hacemos esto a través de un gran contenido y una estructura clara.
El humor es bienvenido, pero solo si encaja naturalmente. Lo más importante es que queremos ayudar a nuestros clientes sin menospreciarlos o asumir que saben todo.
Manténlo Simple: Usa un lenguaje claro y fácil de entender. Evita oraciones largas y confusas y palabras complicadas. Usa voz activa para hacer que la escritura sea directa y fácil de leer.
Sé Respetuoso: Escribe de una manera que trate al lector como un igual. No asumas que ya saben cosas. Asegúrate de proporcionar todos los detalles que necesitan, con enlaces a más información si es necesario.
Sé Claro y Útil: Enfócate en dar información útil en lugar de largas explicaciones. Guía a los lectores paso a paso, y piensa en lo que podrían buscar para que puedan encontrar las respuestas fácilmente.
Usa Humor con Cuidado: El humor es genial si encaja naturalmente, pero nunca debe ser forzado. 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. Se anima el humor, pero solo si se ajusta a la mentalidad que tiene un usuario al leerlo. Piensa en por qué los usuarios están aquí. Si un usuario lee un artículo que explica cómo funciona la Búsqueda, es probable que esté en una mentalidad de descubrimiento, y el humor puede funcionar bien.
Sin embargo, si están navegando por preguntas frecuentes o artículos de solución de problemas, es probable que ya estén molestos por un problema y simplemente necesiten una solución clara. La mentalidad importa ;)
Cuando se usa humor, hazlo nerd - Nos encantan las referencias a Star Wars, El Señor de los Anillos, Matrix y otros fenómenos de la cultura geek. A menudo funciona 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 característica. Los lectores suelen estar en modo de descubrimiento al leer estos y quieren entender cómo funciona. Estos artículos no incluyen pasos o una guía exhaustiva a través del backend, pero explican claramente cómo funciona cada parte.
Ejemplos:
Cómo Hacer #
Explica cómo lograr un cierto resultado. Estos requieren una guía paso a paso que explique los botones exactos que los usuarios deben hacer clic y las configuraciones que deben seguir. Los lectores suelen intentar lograr algo específico al leer estos.
Ejemplos:
Preguntas Frecuentes / Solución de Problemas #
Explica las soluciones más probables a preguntas o problemas comunes. Los lectores a menudo están frustrados hasta cierto punto al navegar por estos, porque algo no funciona como se esperaba. Estos deben estar claramente etiquetados con la pregunta que un lector tendrá en mente y proporcionar explicaciones claras de cómo resolverlo.
Estos nunca son artículos individuales, sino que se recopilan bajo Preguntas Frecuentes para un producto, característica o integración específica.
Ejemplos:
Intros #
¿Notaste 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 intros son todo sobre explicar por qué algo es importante de leer. Se trata de captar la atención de los lectores y permitirles detectar rápidamente si han encontrado el contenido o no.
Las intros no deben ser demasiado largas, pero deben dar a los lectores el contexto de lo que están a punto de leer.
Siempre incluye intros al principio 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 un máximo de 3 palabras, y idealmente solo 1.
Un buen título es “Omnisearch”. Una mala versión es “Nuestra Función Omnisearch”. Agrega demasiadas palabras innecesarias y hace que sea más difícil navegar por la estructura del menú.
Los títulos cortos funcionan bien porque son fáciles de navegar, y combinados con una estructura de menú lógica, mantenemos el Centro de Conocimiento fácil de navegar.
Las descripciones de los artículos deben ser una sola frase que agregue 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 tu descripción - debe complementarlo.
Una buena descripción para Omnisearch es: “Una ventana de página completa que sirve a tus visitantes con los resultados que son más propensos a convertir”. Explica claramente qué es Omnisearch, en una sola frase.
Una mala es: “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 es claro en el menú del Centro de Conocimiento.
Encabezados #
Estos son cruciales para hacer que los artículos sean fáciles de escanear y navegar. Úsalos para separar claramente diferentes partes.
Los encabezados son jerárquicos y siempre se utilizan 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 más pequeños que h4.
Todos los h2 y h3 se utilizan 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, rara vez leerán el artículo completo, sino que lo escanearán para encontrar las partes que necesitan.
El párrafo ideal tiene entre 1 y 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 (cuando se visualiza en una laptop de 13 pulgadas).
Esto no es un requisito estricto, pero es una buena regla general. Nuestros cerebros tienden a mirar bloques grandes de texto y deducir que son difíciles de leer, incluso si no lo son.
Para visualizar la diferencia que hace, revisa la sección a continuación, donde se han eliminado los saltos de línea. Más difícil de escanear, ¿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 escanearán para encontrar las partes que necesitan. El párrafo ideal tiene entre 1 y 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 (cuando se visualiza en una laptop de 13 pulgadas). Esto no es un requisito estricto, pero es una buena regla general. Nuestros cerebros tienden a mirar bloques grandes de texto y deducir que son difíciles de leer, incluso si no lo son. Para visualizar la diferencia que hace, revisa la sección anterior, donde se han agregado los saltos de línea. Más fácil de leer, ¿verdad?
Enlaces #
Siempre que tenga sentido, incluye enlaces a otras partes del Centro de Conocimiento. Ten en cuenta que el usuario debe tener todo lo que necesita 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 bloque de Contenido. Puedes hacer esto desde Recommendations > Content > Create New. Lee más sobre Contenido aquí.
Capturas de pantalla #
Usamos Brandbird para crear capturas de pantalla elegantes. Siempre incluye un buen fondo de contraste para tu captura de pantalla, que no robe atención, sino que la complemente.
Las capturas de pantalla son importantes porque 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. La redacción hace eso.
Una buena regla general es incluir un máximo del mismo número de imágenes que tienes encabezados h2 y h3. Menos también está bien - a menudo, menos es más cuando se trata de capturas de pantalla.
Revisa cómo Linear utiliza capturas de pantalla de manera moderada y usa buena redacción para complementarlas.
Una captura de pantalla debería cubrir generalmente toda la extensión de una página, seguida de texto que explique los pasos a seguir o las características que están disponibles.
Por ejemplo, en lugar de mostrar 3 imágenes diferentes para HTML, CSS y Sub-Diseños por separado, es mejor una sola que muestre todo en el párrafo inicial. Las anotaciones también son bienvenidas para ayudar a aclarar partes de una imagen.
Videos #
Usamos Loom o Tella para grabar videos. Usa sus respectivas funciones de Incrustar y recuerda elegir siempre la versión Responsiva. Pueden ser añadidos directamente a un artículo así:
Los videos son geniales para mostrar claramente todos los aspectos de una característica o cómo hacer algo específico. Complementan bien las guías, ya que los lectores a menudo pueden comenzar viendo el video, antes de usar el artículo como referencia.
Sin embargo, los videos nunca deben reemplazar el texto escrito, así que cualquier cosa mostrada en un video también debe estar escrita en texto.
Al grabar videos, pasa por los puntos cronológicamente en el mismo orden en que escribiste el artículo, para que sean fáciles de seguir.
Elementos del menú #
Organizamos el Centro de Conocimiento lógicamente, y generalmente en el mismo orden en que se muestran las características en nuestro backend.
Solo los artículos que son aplicables a todos los clientes deben tener sus propias páginas. Cualquier caso especial debe ser agregado bajo Preguntas Frecuentes para el aspecto relevante.
Ejemplos:
- 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 rastreados no se muestran en el dashboard es un caso especial, y se coloca en la FAQ para Any (Webshop)
Hugo #
Todo nuestro Centro de Conocimiento está escrito 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 maravillosamente a través de nuestro tema.
Consulta cómo comenzar 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 de integraciones y plataforma.
Las traducciones son manejadas por Localazy como puedes ver en el archivo README.md en la carpeta raíz.
La estructura de archivos se asemeja estrechamente a la estructura del menú, porque Hugo renderiza 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 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 ser sobrescrito 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 de búsqueda)
│ └── writing (este artículo)
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml <-- configuración del sitio
La URL para cada artículo se genera en función de la estructura de carpetas hasta la última capa, donde se encuentra el archivo _index.md. La URL para el ejemplo anterior es /integrations/act-on/email-recs
Front Matter #
Estos son los metadatos que puedes agregar a los artículos, como títulos, descripciones, alias (redirecciones), categorías y más.
El front matter siempre se encuentra en la parte superior de un artículo:
---
title: "Santo Grial"
onPageTitle: "Cómo encontrar el Santo Grial"
description: "La mejor película de Monty Python con diferencia"
weight: 3
aliases:
- /old/path/to/holy-grail
- /really/old/path/to/holy-grail
---
¿Cuál es la velocidad del aire de una golondrina sin carga?...
El front matter más importante es:
- title: Un título personalizado para el artículo, utilizado para personalizar su punto en el menú. Si no se incluye, se utilizará el nombre de la carpeta en formato de título.
- onPageTitle: Un título que solo se muestra en la página del artículo, no en el menú. Esto es bueno para propósitos de SEO donde el título de la página podría ser “Cómo funcionan las Lógicas de Producto”, mientras que el artículo aún se lista como “Lógicas” en el menú.
- description: Se muestra justo debajo del título en la página del artículo. Esto es requerido ya que proporciona un contexto valioso al lector.
- weight: La posición del artículo en el menú. Cuanto menor sea el número, más arriba se mostrará en el menú.
- aliases: URLs antiguas donde este artículo ha estado ubicado 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, deberás agregar su URL anterior como un alias aquí. Pero en general, no cambies los nombres de las carpetas. Usa title en su lugar.
Markdown #
Un gran lenguaje de marcado que te permite enfocarte completamente en el contenido, en lugar de también luchar 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 una hoja de trucos, consulta el sitio oficial.
A continuación se presentan las reglas de sintaxis más comunes que necesitas.
Encabezados #
Se pueden agregar usando una cantidad de # seguida del texto del encabezado.
El número de hashtags decide el encabezado:
h2: ## Shortcodes
h3: ### Sus sintaxis
h4: #### Una sintaxis específica
Párrafos #
Cualquier texto en la misma línea o en la siguiente se muestra como un solo párrafo. Agregar 1 línea de espacio entre líneas separa los párrafos:
Todo el texto aquí es un párrafo.
Incluso el texto aquí estará en la misma línea que el anterior.
El texto mostrado aquí obtiene su propio párrafo.
Enlaces y Anclas #
Se pueden agregar simplemente resaltando el texto para el que deseas crear un enlace y envolviéndolo en llaves seguido de un paréntesis con el enlace.
... lee más sobre [Contenido aquí](/platform/content/settings/)
Al referenciar artículos en el Centro de Conocimiento, 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 más largos, usando # seguido del ID de un encabezado en la referencia.
El ID es una versión sanitizada del nombre. Por ejemplo, el encabezado “Para Desarrolladores” obtendrá el ID for-developers.
Esto se puede usar para referenciar encabezados dentro del artículo mismo, o para referenciar otros artículos incluyendo también su ruta relativa:
Revisa la sección [Para Desarrolladores](#for-developers) más abajo.
Revisa [Errores de sincronización comunes para Magento2 aquí](/integrations/magento-2/faq/#common-sync-issues).
Imágenes #
Usamos un shortcode personalizado para mostrar capturas de pantalla en los artículos.
Siempre debes exportar imágenes como .webp desde
Brandbird para mantener la calidad alta y el tamaño del archivo bajo.
Las imágenes se guardan en la misma carpeta donde se encuentra 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 puedan entender lo que se muestra en ellas.
Referencias de UI #
El Centro de Conocimiento se traduce automáticamente, por lo que para evitar traducir elementos del menú, usamos un shortcode específico para referenciar nuestra interfaz de usuario.
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 encabezados de manera diferente a la del resto del texto:
{{% uiref "Search > Designs > New Design > Omnisearch" %}}
La salida de esto se mostrará como texto en negrita que permanece igual en todas las traducciones: Search > Designs > New Design > Omnisearch
Llamadas de atención #
Estos son cuadros de color que se pueden usar para resaltar puntos importantes. Deben usarse con moderación, y solo cuando algo sea especialmente importante.
Esto también significa que cualquier artículo individual generalmente no debe contener más de 1 de cada uno de estos, ya que de lo contrario complican el artículo.
La sintaxis es:
{{< hint info|warning|danger >}}
**Algo**: Para tener en cuenta.
{{< /hint >}}
Hay tres tipos de llamadas de atención:
Información sobre algo que es bueno saber, como nuestra sugerencia para una plantilla de inicio.
Advertencia sobre algo que podría convertirse en 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 crear primero una copia de seguridad.
Úsalos solo cuando sea realmente necesario, y de acuerdo con la gravedad de lo que explican.
Bloques de código #
Estos vienen en dos variaciones - en línea y bloque.
Un bloque de código en línea que se crea usando dos comillas invertidas `así`.
Los bloques de código completos se crean envolviendo el código con 3 comillas invertidas al principio y al final, y agregando el lenguaje de código para la sintaxis:
console.log("¡Qué gran ejemplo de código!");
Comienza a escribir #
¡Ahora estás listo para comenzar a escribir contenido de clase mundial!
Hay mucho que digerir en este artículo, y probablemente no recordarás la mitad de ello mañana. Tómate un descanso, come algo y léelo de nuevo.
Luego, encuentra un artículo en el Centro de Conocimiento que creas que podría ser mejor, y reescríbelo usando estas pautas. Mantén esta guía abierta cuando escribas, para que puedas referenciarla.
Cuando hayas hecho lo mejor que puedas, busca comentarios de un colega - no tiene que tomar más de 10 minutos, y podrán detectar aspectos que podrías no haber notado.
Todos se vuelven miopes al escribir, así que los comentarios son cruciales 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.