Como colaborador de la base de conocimientos, usas palabras para ayudar a quinientos millones de usuarios. Es un gran trabajo. Los usuarios llegan a la base de conocimientos de todas partes del mundo y esperan soluciones fáciles, pero también queremos deleitarlos con nuestra voz. ¿Cómo se hace eso? Aquí hay algunas cosas que se nos ocurrieron en nuestra investigación.

Tono

Escribe con la marca en mente. Mozilla se trata de la elección del usuario. Creemos en la libertad y la flexibilidad. Valoramos la privacidad y la seguridad. Somos una organización sin fines de lucro impulsada por la comunidad con colaboradores de todo el mundo que comparten valores comunes.

No es necesario que insistas con esta historia cada vez que escribes un artículo. Es solo algo a tener en cuenta cuando describes las características.

Estilo de escritura

Escribe para un público general y no técnico.

Queremos que nuestros artículos sean útiles para todos los usuarios, no solo para los más avanzados. Es decir, queremos que los artículos sirvan de ayuda a una gran mayoría de personas, no a una minoría experta en términos de informática y tecnología. Tienes que tener siempre presente que la persona que leerá el artículo quizás no sepa cambiar las preferencias o añadir un nuevo botón a la barra de herramientas sin unas instrucciones debidamente detalladas. Además, también tienes que asumir que seguramente no hayan cambiado ninguna de las preferencias por defecto de la aplicación o de su sistema operativo.

Para resumir, debes seguir estas pautas:

1. Sé breve. La gente viene a la base de conocimientos en busca de soluciones rápidas. Puede que no les importe el funcionamiento interno de la herramienta, solo quieren saber qué deben hacer ellos para solucionarlo. Anímate y recorta algunas palabras. Mira cuánto puedes transmitir con menos palabras. ¡Es como la poesía!
2. Sé claro. Evita la jerga. Sé específico. Usa palabras en el título y en el artículo que el lector usaría. Si tu sobrino de 13 años no lo entiende, escríbelo para que lo haga. Consulta la siguiente sección para una guía más extensa.
3. Sé amigable, divertido y empático. (En resumen: sé humano). De acuerdo, los usuarios no esperan diversión en el soporte. Eso es lo que lo hace poderoso. Alégrale el día al usuario con un poco de humor. Pero ten cuidado de no sacrificar la claridad usando metáforas o expresiones divertidas. Si no estás seguro de cómo equilibrar esto, simplemente escribe instrucciones directas y usa el tono en la introducción o conclusión.
4. Cuenta una historia. Ten un principio, un desarrollo y un final. Pero no escribas una novela (ver pauta #1).
   • Principio: esto le da al lector algo de contexto. ¿De qué trata este artículo y por qué debería importarme? Sé breve.
   • Desarrollo: Las instrucciones van aquí. Esto debería responder a "¿Cómo hago esto?".
   • Final: ¿Hay algún paso siguiente para el artículo o la característica? Dile al lector a dónde debe ir a continuación si quiere aprender más.

Lee la siguiente sección para obtener pautas más completas.

Estilo de escritura (exhaustivo)

• Estilo de escritura conversacional – Usa un estilo informal y activo similar a la forma en que hablarías con alguien en persona.
• Humor y emoción – Usar el humor es genial, pero a veces es difícil o imposible de localizar. Emociones como la sorpresa y los momentos "¡No sabía eso/Eureka!" podrían ser más fáciles de incluir.
• Múltiples estilos de aprendizaje – Al igual que en la escuela, las personas aprenden de manera diferente. Además, todos se benefician de ver el mismo contenido expresado de múltiples maneras.
• Repetición – Cuando explicas algo de una manera diferente con diferentes medios, también lo estás repitiendo, obviamente, lo cual es otra buena manera de ayudar a las personas a recordar lo que es importante.
• Imágenes y video – Usar imágenes y video junto con texto no solo es lo más parecido a ayudar en persona, sino que es una manera fácil de incluir múltiples estilos de aprendizaje y repetición. Sin embargo, demasiadas imágenes pueden dificultar la localización de un artículo, así que intenta agregar imágenes solo cuando sea útil para un paso o concepto. Por ejemplo, para un paso que consiste en hacer clic en un botón, podrías decir "Haz clic en OK" en lugar de agregar una captura de pantalla del cuadro de diálogo de ese botón.
• Actividades – Especialmente en un tutorial, es bueno dar a la gente algo útil que lograr. Una cosa es leer las instrucciones y entender el proceso, pero a menudo es útil recordar y permitir que la gente pruebe las cosas.

Tipos de artículo

El uso de tipos de contenido consistentes para nuestros artículos de la base de conocimientos tiene muchos beneficios, incluyendo la facilidad de navegación y una mayor claridad y organización, además de ayudarnos a crear contenido de manera más efectiva. Estamos en transición hacia la categorización de los artículos externos de la base de conocimientos en cuatro tipos, cada uno con un propósito específico:

• Acerca de: Estos artículos abordan preguntas de tipo "¿Qué es...?", proporcionando información esencial para ayudar a los lectores a entender un tema.
• Guía práctica: Estos artículos se centran en responder preguntas de tipo "¿Cómo...?", guiando a los lectores a través de los pasos necesarios para lograr un objetivo o procedimiento específico.
• Solución de problemas: Estos artículos ayudan a los usuarios a identificar, diagnosticar y resolver problemas comunes que pueden encontrar con un producto, servicio o característica, abordando preguntas de tipo "¿Cómo...?" relacionadas con la resolución de problemas.
• Preguntas frecuentes (FAQ): Estos artículos contienen respuestas concisas a preguntas frecuentes sobre un solo tema, que pueden no encajar en otros artículos individuales de la base de conocimientos, proporcionando una referencia rápida para consultas comunes.

Comienza con un título efectivo y descriptivo

Un título bien elaborado es más que una simple etiqueta; es el primer punto de contacto del usuario con tu artículo de la base de conocimientos. Un buen título no solo debe captar la atención del lector, sino también servir como una vista previa concisa e informativa del contenido del artículo. Al crear títulos para SUMO, considera lo siguiente:

• Claridad y descripción: Haz que coincida con el tema del artículo y lo que el usuario está buscando. Sé conciso, pero centrado en el usuario.
• Inclusión de palabras clave: Incorpora palabras clave relevantes para mejorar la visibilidad en los motores de búsqueda y ayudar a los usuarios a encontrar tu artículo.
• Concisión: Mantén los títulos breves pero proporcionando información adecuada. Los títulos más cortos suelen ser más fáciles de usar. Intenta mantener los títulos alrededor de 60 caracteres.
• Orientado a la acción: Usa verbos de acción cuando sea aplicable para indicar lo que los usuarios pueden hacer para resolver un problema o lograr un objetivo. Evita el uso de gerundios (palabras que terminan en "-ando" o "-iendo") en los títulos para asegurar que permanezcan orientados a la acción. Evita usar títulos que contengan "Cómo...".

Escribe una buena introducción

Junto con el título y la tabla de contenidos, la introducción es lo que ayudará al usuario a determinar si está en el lugar correcto.

• Para un artículo "Acerca de": Proporciona una descripción textual o definición del concepto y céntrate en por qué debería importarle al usuario.
• Para un artículo de "Guía práctica": Proporciona una descripción textual o definición de la tarea y céntrate en la importancia o los beneficios de la misma.
• Para un artículo de "Solución de problemas": Describe el problema específico o los síntomas que los usuarios pueden encontrar. Escribe en un lenguaje claro y conciso, evitando la jerga técnica siempre que sea posible.

Ten en cuenta que una buena introducción generalmente puede servir como un buen resumen de búsqueda. A menudo puedes simplemente copiarla en el campo "Resumen de resultados de búsqueda" y listo.

Organiza el artículo eficazmente

La idea general aquí es intentar desarrollar habilidades de lo simple a lo complejo, mientras se intenta mantener la información que la mayoría de la gente necesita cerca de la parte superior. Así, una solución simple y común normalmente vendría antes que una solución compleja o para un caso particular.

Haz que las instrucciones paso a paso sean fáciles de seguir

Lo principal a tener en cuenta al escribir instrucciones paso a paso es tener cuidado de incluir todas las acciones necesarias para completar la tarea. Si, por ejemplo, tienes que hacer clic en OK después de seleccionar una preferencia para pasar al siguiente paso, asegúrate de incluir el clic en “OK” como parte de ese paso. Algunas cosas adicionales a considerar:

• Siempre hay múltiples formas de lograr un resultado. Siempre debemos elegir la forma más fácil de usar utilizando la interfaz gráfica de usuario y los menús cuando sea posible.
• Usa oraciones completas al describir cómo acceder a la interfaz de usuario.
• Incluye los resultados esperados al dar instrucciones (por ejemplo, Haz clic en “OK” y la ventana se cerrará.).

Legibilidad

El texto debe ser legible. Para ello, debes:

• Dividir un artículo en pequeños bloques lógicos/semánticos con subtítulos.
• Usar listas numeradas o con viñetas.
• Escribir oraciones cortas o relativamente cortas.
• Evitar escribir párrafos grandes.

No hay límite en la cantidad de texto. Cuanto más material, mejor; sin embargo, no debes expandirlo artificialmente. Proporciona solo información útil, valiosa y necesaria.

Cómo enlazar a documentación externa para software de terceros

Al crear o actualizar artículos que involucran acciones dentro de software de terceros, como sistemas operativos o aplicaciones externas, es crucial proporcionar a los usuarios información precisa y confiable. Sin embargo, incluir pasos directos para este software en nuestros artículos puede presentar desafíos:

• Información que se desactualiza rápidamente: Las actualizaciones de software de terceros pueden hacer que nuestras instrucciones queden obsoletas, lo que podría confundir o engañar a nuestros usuarios.
• Intensivo en recursos: Monitorear y actualizar continuamente los pasos para múltiples plataformas externas requeriría un esfuerzo y recursos significativos, lo que puede no ser factible.

Buenas prácticas

Para asegurar que nuestros usuarios reciban la información más confiable y actualizada sin sobrecargar nuestros recursos, sigue estas buenas prácticas:

• Enlaza a recursos oficiales: Siempre que las instrucciones involucren software de terceros, encuentra la documentación oficial o los artículos de ayuda proporcionados por el fabricante del software. Enlaza a estos recursos en lugar de escribir los pasos directamente en nuestros artículos.
• Proporciona contexto: Explica brevemente por qué estás dirigiendo al usuario a una página externa (por ejemplo: "Para los pasos más recientes y precisos para ajustar la configuración de tu sistema, consulta la página de soporte oficial de [nombre del software]").
• Verifica los enlaces periódicamente: Aunque nuestro objetivo es reducir el mantenimiento de las instrucciones de terceros, sigue siendo importante verificar periódicamente que los enlaces externos sigan siendo válidos. Si notas que un enlace se ha vuelto obsoleto o está roto, busca un enlace actualizado a la documentación oficial y envía una revisión.
• Descargo de responsabilidad sobre contenido externo Al dirigir a los usuarios a un enlace externo, deja en claro que abandonarán SUMO y que no somos responsables del contenido de los sitios externos. Un simple descargo de responsabilidad o nota puede ser suficiente (por ejemplo, "Seguir este enlace te redirigirá a un sitio web externo que no es operado por Mozilla.").

Ejemplo

Imagina que estás escribiendo un artículo sobre la configuración de una función de Firefox que depende de cambiar la configuración a nivel del sistema en una Mac. En lugar de detallar los pasos directamente en el artículo, podrías escribir:

"Para conocer los pasos más recientes para ajustar las preferencias del sistema en macOS, consulta la documentación de soporte oficial de Apple visitando esta guía. Ten en cuenta que seguir ese enlace te dirigirá a un sitio web externo que no es operado por Mozilla.".

Esto asegura que estás siguiendo las instrucciones más actuales directamente desde la fuente.

Directrices técnicas

• Para aprender cómo crear un nuevo artículo, consulta Cómo crear un nuevo artículo para la Base de Conocimiento.
• Para aprender a editar un artículo existente, consulta Editar un articulo en base a Conocimientos.
• Consulta Cómo funciona la Base de Conocimiento para una visión general de cómo funciona la Base de Conocimientos.
• Consulta Mejora la base de conocimientos para una lista completa de la documentación de artículos.

Título

• Longitud del título: la página de resultados de búsqueda de Google mostrará hasta 60 caracteres. Tu título puede ser más largo si es necesario, pero asegúrate de que tus palabras clave importantes estén incluidas en los primeros 60 caracteres.
• Mayúsculas: Usa mayúsculas de tipo oración. La primera palabra del título debe ir en mayúscula, así como los nombres propios y los nombres, no todas las palabras importantes. Usa estilo de "frase", no estilo de "título" (lo mismo se aplica a los títulos de las secciones). Consulta la sección Guía de estilo y reglas de redacción a continuación para otras reglas sobre el uso de mayúsculas.
• No uses dos puntos en el título del artículo, ya que impide la creación de un enlace wiki a ese artículo (bug 749835). Asegúrate también de que no haya espacios adicionales en el título del artículo, lo que también impedirá que los enlaces wiki funcionen.
• Intenta variar la forma en que nombras los artículos. No uses las mismas palabras o frases en cada título. Por ejemplo, no siempre comiences los artículos con "Cómo" y evita usar nombres de tareas con gerundio como "Configurando la página de inicio".
• Recuerda que toda la explicación no tiene que ir en el título. Puedes usar el resumen para dar al usuario información adicional sobre lo que hay en el artículo.

Slug

Cuando creas un nuevo artículo e introduces un título, SUMO creará automáticamente un slug (la parte después de kb/ al final de la URL del artículo). Un revisor puede editar el título de un artículo existente, pero el slug permanece igual, a menos que se cambie manualmente (esto es por diseño). El slug tiene un límite de 50 caracteres. Los espacios se representan como guiones. El slug debe ser coherente con el título, pero dada la restricción de espacio más estricta, no necesita ser el mismo.

Arreglar el slug

Asegúrate de revisar el final del slug autogenerado. A veces una palabra se corta o termina en un guion. Por favor, arregla cosas como esa.

Actualizar el slug de un artículo existente

Cuando actualices el título de un artículo existente, mantén el slug actual sin cambios a menos que el nuevo título represente un cambio significativo que ya no se alinee con el slug existente. Mantener el slug consistente ayuda a evitar enlaces rotos y preserva el valor de SEO.

Categorías, productos y temas

En su mayor parte, un artículo pertenece a la categoría Guía práctica o Solución de problemas. Ocasionalmente, escribimos artículos en una de las otras categorías, como los artículos de "Cómo contribuir" (como este). La página de Historial del artículo mostrará la categoría.

Los artículos también son "relevantes para" al menos un producto. También pertenecen a un "Tema" principal y, opcionalmente, a un "subtema".

Palabras clave

El campo de las palabras clave en un artículo se utiliza para mejorar los resultados de búsqueda en SUMO. Solo debería utilizarse en determinadas circunstancias, ya que, si se utiliza mal, puede afectar negativamente a los resultados de búsqueda. Muy rara vez las usamos. Para más información, consulta el artículo Cuándo y cómo utilizar las palabras clave para mejorar la búsqueda de un artículo.

Escribe un buen resumen de búsqueda

El resumen del artículo, junto con el título, ayuda a los usuarios a juzgar si un artículo responderá a su pregunta. A esto lo llamamos "Confianza del usuario" y afecta directamente a las tasas de clics. Incluso si ofrecemos el artículo correcto en la parte superior de la lista de resultados de búsqueda, el usuario necesita hacer la conexión mental entre la consulta de búsqueda y los resultados que mostramos para que hagan clic en el artículo.

Un resumen para un artículo de guía práctica debe incluir los temas cubiertos en el artículo. Un artículo de solución de problemas debe intentar incluir los síntomas. Además, un resumen debe seguir estas pautas:

• Corto y al grano. ¿Recuerdas los anuncios clasificados? Escríbelo así. Los motores de búsqueda pueden cortar cualquier cosa que supere los 140 caracteres. Si usas un resumen más largo, mantén la información importante al principio. Nota: El software de la Base de Conocimientos mostrará 20 caracteres restantes cuando el resumen alcance los 140 caracteres porque el límite de búsqueda interno es de 160.
• No uses marcado wiki.
• No uses "Este artículo explica" en cada resumen. Varíalo cuando sea posible. Algunas otras frases a considerar:
  • Te mostraremos
  • Te explicaremos
  • Esta página explica
  • Este artículo describe
  • Aprende cómo

Número de pasos

Al guiar a los usuarios a través de un proceso, considera las listas ordenadas (listas numeradas). Generalmente es una buena práctica intentar mantener el número total de pasos en el rango de seis a siete.

Estructura paralela

Usa la misma redacción o patrón de palabras para cada paso que escribas. La estructura paralela es importante en los artículos de la base de conocimientos porque hace que las cosas sean claras y fáciles de seguir. Cuando elementos similares tienen un formato consistente, los usuarios pueden entender y completar tareas más fluidamente. Esta estructura simplifica las instrucciones, reduce los errores y asegura que la información se transmita de manera efectiva.

Por ejemplo:

1. Encuentra Limpiar el historial cuando Firefox se cierre. Si está seleccionado:
   1. Haz clic en el botón Settings….
   2. Asegúrate de que Historial de formularios y búsquedas no esté seleccionado.
   3. Haz clic en OK.

Indicaciones direccionales

Las indicaciones direccionales son referencias o indicadores que guían a los usuarios a la ubicación o posición específica dentro de una interfaz de usuario donde necesitan realizar una acción particular. Estas indicaciones ayudan a los usuarios a navegar e interactuar con software, aplicaciones o sitios web de manera más efectiva. Típicamente incluyen frases como "En la esquina superior derecha", "En el menú de la izquierda" o "Debajo de la barra de búsqueda", que proporcionan a los usuarios una idea clara de dónde encontrar y realizar acciones.

En las instrucciones de tu artículo de la base de conocimientos, asegúrate de proporcionar indicaciones direccionales antes de la acción. Por ejemplo, en lugar de decir Haz clic en el botón, usa En la esquina superior derecha, haz clic en el botón. Este formato ayuda a los usuarios a localizar y realizar acciones fácilmente dentro de la interfaz.

Guía de estilo y reglas de redacción

Como dijimos antes, debes usar un estilo activo y conversacional cuando escribas. Evita decir cosas como "Si los marcadores de un usuario se han perdido" y en su lugar di "Si has perdido tus marcadores". Aquí hay otros problemas comunes de estilo y redacción que puedes encontrar al escribir artículos de soporte: Usa siempre los términos tal como aparecen en la interfaz de Mozilla. Por ejemplo:

• Plugins no lleva guion.
• Add-ons sí lleva guion.
• Home page son dos palabras.

Términos generales de informática:

• Website es una palabra. Web page son dos palabras.
• Log in y log out son verbos. Ejemplo: "Inicia sesión en el sitio web". Lo mismo se aplica a sign in y sign out. No uses "log into" o "sign into".
• Login y logout son sustantivos (generalmente usados como adjetivos). Ejemplo: "Haz clic en el botón de inicio de sesión".
• Usa email en lugar de e-mail.
• El plural de CD-ROM es CD-ROMs.

Los enlaces a mozilla.org no deben contener la configuración regional:

• Usa https://www.mozilla.org/ en lugar de https://www.mozilla.org/en-US/

Al incorporar enlaces en las oraciones:

• Evita usar "haz clic aquí" o "aquí" como texto del enlace.
  • Correcto: Ve a la configuración de tu cuenta para cancelar tu suscripción.
  • Incorrecto: Haz clic aquí para cancelar tu suscripción.

Pon en mayúscula los siguientes elementos:

• Nombres propios y nombres, incluyendo nombres de marcas, productos y características
• La primera palabra de una oración completa
• Las letras de abreviaturas y acrónimos, a menos que normalmente vayan en minúsculas
• La primera palabra en listas numeradas o con viñetas
• El nombre de una tecla en el teclado
• La primera palabra de una oración completa después de dos puntos
• La primera palabra en un encabezado o título

Mozilla accounts:

• La "a" en Mozilla accounts siempre va en minúscula, excepto en los elementos de navegación donde se incluye con otros elementos de navegación que usan mayúsculas de título.
• Usa siempre "sign in" y "sign out".
• En forma verbal, usa "sign in to your account" (no "sign into") para ser gramaticalmente correcto.
• También puedes usar "Sign in with Mozilla".
• "Sign" siempre debe usarse como verbo. Si lo usas como sustantivo, usa "login".
• Usa "sign up" como llamada a la acción para crear una nueva cuenta.

Para más detalles sobre cómo referirse a Mozilla accounts en los artículos de la base de conocimientos, consulta Editorial guidelines for Mozilla accounts.

No uses “i.e.” y “e.g.”. Estas abreviaturas latinas pueden confundir a la gente. En aras de la claridad, usa "en otras palabras" o "dicho de otro modo" en lugar de i.e. cuando quieras explicar algo de una manera diferente. Usa "por ejemplo" o "tal como" en lugar de e.g. cuando quieras dar ejemplos.

No uses comas seriales en una lista de elementos. Por ejemplo, usa "Extensiones, temas y plugins" (sin la coma serial), no "Extensiones, temas, y plugins".

Usa inicialismos que se consideren de comprensión general. Por ejemplo:

• HTTP
• USB
• URL

Los Números que aparecen en la versión de un producto, códigos de error, teclas y botones no se escribirán con letra.

Escribe las instrucciones en voz activa. Escribe las instrucciones en voz activa. La voz activa y el tiempo presente simplifican las instrucciones, haciéndolas más fáciles de seguir y fomentando una acción rápida. Ejemplo:

"Reinicia Firefox para actualizar" no "Firefox tiene que ser reiniciado".

Escribe las barras invertidas(\) y las barras diagonales(/) para rutas y búsquedas para evitar confusiones.

Ejemplo: "Algunos nombres de ruta a imágenes contienen barras invertidas (\\)".

Atajos de teclado Pon en mayúscula la primera letra de un atajo de teclado o una combinación de atajos: Ctrl + Shift + C o Command + Shift + C.

No uses jerga y modismos. Todos nuestros artículos se traducen a muchos idiomas diferentes, por lo que son leídos y traducidos por hablantes no nativos de inglés. La jerga y los modismos pueden ser ambiguos, lo que puede confundir a los lectores y dificultar la traducción.

Tenemos estilos visuales especiales para una serie de elementos que se pueden lograr añadiendo el marcado wiki adecuado alrededor del elemento. Consulta la Markup cheat sheet para los estilos más comunes.

Tenemos un marcado wiki especial – {for} – que te permite dirigir la información a versiones específicas de Firefox o a sistemas operativos específicos. Por ejemplo, puedes mostrar un conjunto de instrucciones a las personas que usan Windows y otro a las personas que usan macOS X (consulta Cómo utilizar "for" para más detalles).