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 de la Base de conocimientos de la Ayuda de Mozilla ("SUMO"). 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 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.

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.
  • Mayúsculas: La primera palabra y los nombres propios del título deberían ir en mayúsculas, pero no todas las palabras: utiliza un estilo de "frases", no de "títulos". Consulta la guía de estilo de SUMO de este artículo para saber más sobre otras normas en el uso de mayúsculas.
  • 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).
  • Asegúrate de que no haya espacios extra en el título del artículo, ya que evitan que los enlaces a la wiki funcionen correctamente.
  • Intenta ser creativo. No utilices los mismos verbos o frases en todos los títulos.
  • Intenta no usar verbos en gerundio.

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
    • Aprende a

Haz que tu artículo sea más interesante

La Base de conocimientos es un almacén de información técnica sobre todas las operaciones que componen Mozilla. Esta documentación contiene todas las funciones de las distintas características, 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.

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 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".

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 Mozilla. 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.