Cómo escribir artículos de la Base de Conocimiento

Hay muchas cosas que tienes que tener en cuenta a la hora de escribir o editar un artículo. Quieres que esté completo y que sea conciso y realista. Sabemos que no es algo fácil, por eso te ofrecemos algunas instrucciones y ayuda para que el proceso sea mucho más fácil. Además, se trata de un wiki, así que siempre podemos revisarlo por si nos equivocamos en algo.

Escribe para un público general, no para uno especializado

Queremos que la ayuda de Firefox sea útil para todos los usuarios: Esto significa que 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 Firefox o de su sistema operativo.

Elige un buen título

Tanto el título del artículo como el resumen es lo que va a ayudar a los usuarios a decidir si ese artículo resolverá o no sus dudas. Lo que llamamos "Confianza del usuario" y es lo que afecta principalmente a las estadísticas. Aunque el artículo correcto aparezca en lo más alto de la lista de resultados, el usuario tiene que establecer una conexión mental entre las palabras de búsqueda y los resultados que aparecen para poder seleccionar el artículo que necesita.

El título del artículo debería describir de qué va ese artículo. Lo importante es que las primeras palabras sean lo más comprensibles posible y que contenga las palabras clave más importantes. Esto permitirá a los usuarios saber de qué va el artículo y empezar a leerlo estando totalmente seguros. Además, un título debería cumplir los siguientes requisitos:

  • La longitud: La página de resultados de búsqueda de Google muestra como máximo 70 caracteres. Si es necesario, el título puede ser más largo, pero tienes que asegurarte de que las palabras claves están en esos primeros 70 caracteres.
  • Intenta ser creativo. No utilices los mismos verbos o frases en todos los títulos.
  • Intenta no usar verbos en gerundio.
  • No uses dos puntos en el título del articulo ya que hace imposible crear un enlace a ese articulo en la wiki (bug 749835).

Recuerda que el título no tiene que ser una descripción completa del artículo. Para eso tienes la sección de "resumen": ahí puedes facilitar más información sobre el contenido del artículo.

Arreglar la dirección slug

Cuando escribes el título, SUMO creará automáticamente el slug (la parte final de la url del artículo). No debe tener más de 50 caracteres. Los espacios se convierten en guiones. Tiene que estar en consonancia con el título, pero dada la restricción de espacio, no tiene por qué ser el mismo. Asegúrate de comprobar el slug que se autogenera: a veces se corta alguna palabra o termina en un guión. ¡Que esto no pase!

Categorías, productos y temas

La mayoría de los artículos pertenecen a la cateoría de "¿Cómo...?" o están destinados a solucionar un problema. A veces, también escribimos artículos sobre "Cómo colaborar" (como este) o de cualquier otra categoría.

Los artículos también son "importantes" al menos para un producto. Siempre pertenecen a un "tema" principal y, a veces, incluso 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úsquedas

Tanto el título del artículo como el resumen es lo que va a ayudar a los usuarios a decidir si ese artículo resolverá o no sus dudas. Lo que llamamos "Confianza del usuario" y es lo que afecta principalmente a las estadísticas. Aunque el artículo más adecuado aparezca en lo más alto de la lista de resultados, el usuario tiene que establecer una conexión mental entre las palabras de búsqueda y los resultados que aparecen para poder seleccionar el artículo que necesita.

Un resumen para un artículo sobre "¿Cómo...?" debería incluir el tema principal. El resumen para un artículo que resuelve algún problema debería incluir alguno de los síntomas. Además, a la hora de hacer el resumen deberías tener en cuenta lo siguiente:

  • Debe ser corto e ir directo al grano. ¿Sabes lo que son los anuncios clasificados? Pues escribe igual. Los motores de búsqueda eliminan cualquier resultado que supere los 160 caracteres.
  • No utilices el marcado wiki.
  • No utilices "En este artículo te explicamos" en cada artículo. Cambia un poco. Otras frases que puedes utilizar:
    • Te mostramos
    • Te vamos a explicar
    • Este artículo explica

Haz que tu artículo sea más interesante

La Ayuda de Firefox es un almacén de información técnica sobre todas las operaciones que componen Firefox. Esta documentación contiene todas las funciones de las distintas características de Firefox, los procedimientos para solucionar sus problemas e instrucciones para resolver los fallos más comunes. Puedes acceder a esa documentación utilizando la barra de búsqueda presente en cada página o puedes acceder a la sala donde los unicornios utilizan los poderes del arco iris para entrar en el mundo mágico de los caramelos, que te elevará al nivel ninja 70 una vez que te los hayas comido todos.

¿Hemos llamado tu atención? Bien, continuemos.

El párrafo anterior es un auténtico aburrimiento, al menos hasta que aparecen los unicornios. Utilizar el humor y las emociones (¡SORPRESA!) es una de las técnicas que utilizamos para atraer a la gente. Todas esas técnicas, que aparecen más abajo, tienen como objetivo que tu cerebro preste atención haciendo que todo parezca real. Utilizando estas técnicas todo es mucho más fácil de entender y recordar.

  • Escribir como si estuvieras hablando con alguien – Utiliza un estilo informal y activo, parecido al que utilizamos cuando estamos hablando con otra persona.
  • Humor y emociones – El humor es una técnica muy buena, aunque a veces es difícil de entender o encontrar. Sin embargo, emociones como la sorpresa u otras tipo "¡No lo sabía!" (no estamos muy seguros de cómo llamar a esa emoción) pueden ser más útiles.
  • Diferentes estilos de aprendizaje – Como ocurre en el colegio, la gente utiliza distintos métodos para aprender. Además, es mejor para todos que el mismo contenido se exprese de distintas formas.
  • Repetición – Explicar algo de una forma distinta y por diferentes medios, es una forma de repetir y de ayudar a la gente a entender qué es importante.
  • Imágenes y vídeo – El uso de imágenes y vídeos para explicar lo que dice el texto no es solo una mejor forma de ayudar al usuario, sino que también supone una forma fácil y sencilla de incluir diferentes estilos de aprendizaje y repetición.
  • Actividades – Sobre todo en los tutoriales, es bueno dar a los usuarios algo que comprobar. Una cosa es leer las instrucciones y entender el proceso y otra hacer que la gente practique y pruebe lo que han leído para ver si es verdad que lo han entendido.

El artículo Cómo establecer la página de inicio es un buen ejemplo, ya que utiliza la mayoría de estas técnicas.

Escribe una buena introducción

Junto con el título y la tabla de contenidos, la introducción es lo que hará que la gente sepa si está leyendo el artículo adecuado o necesitan buscar otro que se adapte más a lo que están buscando.

  • En un tutorial o un artículo sobre "¿Cómo...?", ofrece un breve resumen de lo que se enseña en ese artículo y qué podemos aprender con él.
  • En un artículo de referencia, escribe una breve explicación de la característica de que se trate.
  • En un artículo que hable sobre cómo solucionar un problema, explica brevemente ese problema y sus síntomas.

Una buena introducción puede servir también como un resumen de los resultados de búsqueda. Puedes copiarlo en la casilla correspondiente y listo.

Organiza adecuadamente el artículo

La idea principal es ir de lo más sencillo a lo más complicado, intentando que lo esencial aparezca al principio del artículo. Es decir, la solución más sencilla y común aparecerá antes que la solución más compleja y difícil de ejecutar.

Utiliza títulos de sección descriptivos

Normalmente, nuestros artículos se entienden perfectamente, así que es necesario incluir títulos de sección descriptivos para ayudar a nuestros usuarios a encontrar fácilmente lo que necesitan. Echa un vistazo a un índice de contenidos. ¿Ofrece una buena introducción sobre el contenido real del artículo?

Cómo hacer que las instrucciones paso a paso sean fáciles de seguir

Lo más importante que tienes que tener en cuenta a la hora de escribir instrucciones paso a paso es de acordarte de incluir todas los pasos necesarios para completar el proceso. Por ejemplo, si tienes que seleccionar "Aceptar" tras seleccionar una preferencia para poder seguir avanzando, asegúrate de incluir que seleccionar "Aceptar" forma parte del proceso. Otras cosas que también debes tener en cuenta son:

  • Hay muchas formas de llegar a un mismo resultado. Intentaremos siempre utilizar la más fácil y asequible: utilizar los menús y la interfaz de usuario cuando siempre que sea posible.
  • Utiliza frases completas cuando describas cómo acceder a la interfaz de usuario.
  • Incluye los resultados que deben obtenerse si se siguen las instrucciones dadas. Por ejemplo, haz clic en "Aceptar" y se cerrará la ventana.

Aquí tienes un ejemplo del artículo Cómo establecer la página de inicio con algunas explicaciones entre paréntesis:

Establece una sola página como tu página de inicio
(Este es el título, en el que se explica qué vamos a lograr)

Si prefieres el camino fácil, te enseñamos cómo establecer tu página de inicio en tres sencillos pasos.
(Este es el contexto, en el que se muestra una gran imagen y se explica por qué lo hacemos)

  1. Abre la página web que quieres establecer como tu página de inicio.
  2. Haz clic en el icono que se encuentra a la izquierda de la dirección web, arrástralo gasta el botón de Inicio y suéltalo.
  3. Haz clic en Sí para establecerla como tu página de inicio.


Inténtalo: Haz clic en el botón de Inicio y se cargará tu nueva página de inicio en esa pestaña. ¡Así de simple!
(Actividad: haz que el usuario siga las instrucciones y describe el resultado esperado).

Los enlaces cortos son optativos

Tenemos una plantilla que se utiliza para compartir artículos que se coloca al final del artículo. Normalmente se utiliza para incluir enlaces a los artículos en los posts que publica nuestra Armada Alucinante.

Si no lo incluyes en tu artículo, asegúrate de reducir la parte de la URL del artículo que no incluye el idioma o cualquier otro caracter extra al final.

Por ejemplo, si abres la página Actualizar Firefox a la última versión puede que veas:

https://support.mozilla.org/en-US/kb/update-firefox-latest-version#os=win7&browser=fx20

Debes cambiarlo y reducirlo para que aparezca así:

https://support.mozilla.org/kb/update-firefox-latest-version

Para crear un enlace mzl.la:

  1. Pega el enlace del artículo en el campo que pone "acortar" en la página https://bitly.com
  2. Edita el enlace, como hemos explicado anteriormente.
  3. Haz click en Acortar.
  4. Haz clic en Copiar en la página que aparece a continuación.

Guía de estilo de SUMO

Como ya hemos dicho antes, a la hora de escribir los artículos deberías utilizar un estilo activo y de conversación. Es decir, evita frases como "Si el usuario ha perdido un marcador..." y cámbiala por "Si han desaparecido tus marcadores...". Estos son otros aspectos que deberías evitar cuando escribas un artículo:

Utiliza siempre los términos tal y como aparecen en la interfaz de Firefox. Por ejemplo:

  • Los plugins no tienen guión.
  • Página de inicio son tres palabras.

Términos generales de informática:

  • Internet se escribe con mayúscula inicial.
  • Página web son dos palabras.
  • Iniciar y cerrar sesión son verbos. Por ejemplo, "Inicia sesión en la página web".
  • Inicio y cierre de sesión son sustantivos. Por ejemplo, "Haz clic en inicio de sesión".
  • Utiliza correo electrónico en vez de e-mail.
  • El plural de CD-ROM es los CD-ROM.

Los enlaces a mozilla.org no deben incluir la localización:

Deben ir con mayúscula inicial:

  • Los nombres propios.
  • La primera palabra de una frase.
  • Las letras de las abreviaciones y acrónimos, excepto cuando su escritura habitual es en minúsculas.
  • La primera palabra de una lista numerada.
  • El nombre de una tecla del teclado.
  • La primera palabra de una frase que empieza tras dos puntos.
  • La primera palabra del título o encabezado.

Para una mejor claridad en la redacción del artículo, no utilices la abreviación de "por ejemplo": p.ej.

Tenemos estilos visuales especiales para un número determinado de puntos que se pueden conseguir añadiendo la marca correspondiente (consulta la Markup cheat sheet para ver los estilos más usados).

  • Nota
  • Advertencia
  • Code
  • nombre del archivo
  • Atajos de teclado como Ctrl + T
  • Menú – Firefox
  • Botones

Tenemos un lenguaje de marcado wiki especial - {for} – que te permite dirigir la información hacia las diferentes versiones de Firefox o para los distintos sistemas operativos. Por ejemplo, puedes mostrar una serie de instrucciones a las personas que ejecutan Windows y otra serie diferente para las personas que utilizan Mac OS X (puedes ver el artículo Cómo utilizar "for" para obtener más información).

¿Te resultó útil este artículo? Espera por favor...

Esta gente maravillosa ayudó a escribir este artículo: Breaking_Pitt, avelper, py_crash. Tú también puedes ayudar, descubre cómo hacerlo.