Guía de estilo

Tabla de contenidos

La guía de estilo define las convenciones de escritura, formato y presentación de los contenidos de este sitio. Su objetivo es mantener la coherencia entre artículos y facilitar el mantenimiento del contenido a lo largo del tiempo.

No es una guía de estilo de escritura general: es específica para este sitio y para el tipo de contenido que publica.

Principios generales de escritura

Claridad antes que elegancia. El objetivo de cada artículo es que el lector comprenda el concepto o la práctica explicada. La prosa elaborada que dificulta la comprensión es un error, no un mérito.

Concreto antes que abstracto. Los principios abstractos se ilustran siempre con ejemplos concretos. Un artículo sobre jerarquía de URLs que no muestra URLs reales es un artículo incompleto.

Activo antes que pasivo. La voz activa es más clara y más directa. “El canonical declara la URL preferida” es mejor que “La URL preferida es declarada mediante el canonical”.

Precisión terminológica. Este sitio tiene un glosario. Los términos técnicos deben usarse con precisión y deben enlazarse al glosario en su primera aparición en cada artículo.

Sin fórmulas de relleno. No “En este artículo aprenderás…”, no “Como hemos visto anteriormente…”, no “En conclusión…”. El contenido habla por sí mismo.

Registro y tono

Registro formal pero no académico. El sitio es formativo y técnico, pero está escrito para profesionales que trabajan en la web, no para un congreso académico. El tono es directo, sin condescendencia y sin informalidad excesiva.

Segunda persona del singular para el lector. “El usuario necesita saber dónde está” cuando se habla de usuarios en general. “Si tienes un blog con varios autores…” cuando se interpela directamente al lector.

Primera persona del plural para el sitio. “En este sitio usamos…” o directamente en pasiva: “Se recomienda…” para evitar la primera persona cuando no es necesaria.

Sin anglicismos innecesarios. Cuando existe un término equivalente en español de uso común, se usa ese. Cuando el anglicismo es el término más extendido en la práctica profesional (como “slug”, “canonical”, “hreflang”), se usa el anglicismo y se explica en el glosario.

Estructura de los artículos

Todos los artículos siguen una estructura coherente:

Título H1: El mismo que el título SEO o una versión ligeramente diferente si el contexto de la página lo justifica.

Párrafo de introducción: No más de dos o tres frases. Presenta el tema y su relevancia. Sin “En este artículo verás…”.

Cuerpo del artículo: Organizado con encabezados H2 para las secciones principales y H3 para las subsecciones. La jerarquía de encabezados debe ser coherente: no saltar de H2 a H4, no usar H2 como si fuera negrita.

Sección “Para profundizar”: Al final de cada artículo, una lista de enlaces internos a artículos relacionados. Mínimo tres, máximo seis. Sin enlaces externos en esta sección (los externos van en el cuerpo del artículo cuando son estrictamente necesarios como referencia).

Uso de tablas

Las tablas se usan para comparaciones entre opciones o para resúmenes de información con múltiples dimensiones. No se usan como sustituto de listas simples o de prosa.

Una tabla bien usada: comparación de ccTLD vs. subdominio vs. subdirectorio con múltiples criterios. Una tabla mal usada: lista de tres elementos con una sola columna.

Las tablas deben tener encabezados de columna claros y deben ser legibles en dispositivos móviles (sin desplazamiento horizontal si es posible).

Uso de código

Los bloques de código se usan para:

  • Ejemplos de HTML, CSS, JavaScript, JSON-LD, XML.
  • Ejemplos de configuración de servidor (Nginx, Apache).
  • Ejemplos de comandos de terminal.
  • Estructuras de URL ilustrativas.

El código en bloque usa la sintaxis de bloque de código Markdown (tres acentos graves con identificador de lenguaje cuando corresponde). El código en línea (nombres de etiquetas, atributos, valores) usa la sintaxis de código en línea.

Todo el código de ejemplo debe ser correcto y funcional, o estar claramente marcado como pseudocódigo simplificado si se ha omitido partes por claridad.

Uso de listas

Las listas numeradas se usan para secuencias de pasos o procesos donde el orden importa. Las listas con viñetas se usan para enumeraciones donde el orden no importa. Las listas no se usan como sustituto de prosa cuando el contenido fluye naturalmente como texto.

Un criterio práctico: si los elementos de la lista son oraciones completas con sentido propio, probablemente es una lista adecuada. Si son fragmentos que solo tienen sentido en el contexto de la frase introductoria, considerar si no sería mejor prosa.

Longitud de los artículos

No hay un límite mínimo ni máximo de longitud. Un artículo tiene la longitud necesaria para cubrir el tema con la profundidad adecuada.

Dicho esto, hay señales de que un artículo es demasiado corto o demasiado largo:

Demasiado corto: No hay ejemplos concretos. No hay casos de uso. El artículo define el concepto pero no explica cuándo ni cómo se aplica. El lector termina de leerlo sabiendo que algo existe pero sin saber qué hacer con esa información.

Demasiado largo: El artículo repite ideas ya expresadas. Hay secciones que podrían ser artículos independientes. La estructura de encabezados tiene más de tres o cuatro niveles de profundidad. El artículo está intentando cubrir más de un tema.

Imágenes y elementos visuales

Las imágenes se usan cuando aportan información que el texto no puede transmitir con la misma eficacia. No se usan como decoración.

Usos adecuados: diagramas de jerarquía, capturas de pantalla ilustrativas, ejemplos visuales de estructura de navegación. Usos inadecuados: imágenes genéricas de “tecnología” o “internet” sin relación directa con el contenido.

Toda imagen tiene:

  • Atributo alt descriptivo del contenido de la imagen (no del texto que la rodea).
  • Título o pie de imagen cuando el contexto lo requiere.
  • Tamaño optimizado para web (no imágenes de alta resolución sin comprimir).

Actualización de artículos

Cuando un artículo se actualiza de forma significativa:

  • Si la actualización corrige información incorrecta: se corrige sin añadir nota visible (salvo que el error haya estado publicado mucho tiempo y haya podido causar confusión).
  • Si la actualización añade información relevante nueva: se puede añadir una nota discreta al inicio o al final indicando la fecha de actualización y el motivo.
  • Si la actualización cambia el enfoque o la tesis del artículo: considerar si es mejor crear un nuevo artículo y redirigir el antiguo.

La fecha visible en el artículo debe reflejar la última actualización significativa, no la fecha de publicación original si el contenido ha cambiado sustancialmente.

Para profundizar