Introducción

Esta guía establece los estándares editoriales para todo el contenido publicado en fronteando.dev. Nuestro objetivo es mantener una voz consistente y profesional que asegure altos estándares de calidad técnica y claridad en la comunicación.

Propósito

• Definir un estándar unificado para la creación de contenido
• Asegurar consistencia en tono, formato y terminología
• Optimizar el proceso de escritura y revisión
• Garantizar la calidad editorial en toda la plataforma

Cómo usar esta guía

Estas pautas proporcionan un marco de referencia flexible que permite la expresión individual mientras asegura coherencia. Las variaciones de estos lineamientos deben tener una justificación clara y mantener el objetivo de proporcionar el mejor valor para nuestros lectores.

• Revisa la guía durante la planificación y escritura
• Aplica estas pautas en tu proceso de revisión
• Usa tu criterio profesional para casos no contemplados
• Propón mejoras cuando identifiques áreas de oportunidad

Principios fundamentales

• Claridad: haz el contenido comprensible para desarrolladores de diferentes niveles
• Utilidad: proporciona valor práctico y aplicable en cada artículo
• Precisión: mantén la información técnica precisa y actualizada
• Accesibilidad: crea contenido inclusivo y fácil de seguir

Tono y voz

El tono y la voz definen nuestra comunicación con la audiencia. Buscamos equilibrar el profesionalismo con la accesibilidad para hacer el contenido técnico comprensible sin sacrificar precisión.

Personalidad

• Combina el expertise técnico con explicaciones accesibles
• Incorpora experiencias personales relevantes para ilustrar conceptos
• Reconoce los retos comunes en el desarrollo
• Explica conceptos complejos mediante analogías prácticas
• Incluye visualizaciones que clarifiquen los conceptos
• Proporciona contexto técnico de manera gradual

Tono

• Comunica de forma directa y clara
• Evita rodeos innecesarios
• Mantén un estilo conversacional
• Usa primera persona solo para experiencias personales
• Emplea segunda persona en las instrucciones
• Prioriza la voz activa en todas las explicaciones

Formato y estructura

Listas y viñetas

• Utiliza guiones para todas las listas
• Omite puntos finales en los elementos
• Mantén la misma indentación para elementos similares
• Comienza cada elemento con mayúscula
• Estructura los elementos de forma paralela

Énfasis y tipografía

Uso de negritas

• Resalta con negritas
  • Conceptos técnicos en su primera mención
  • Elementos clave que definen una sección
  • Palabras de acción en instrucciones

Uso de cursivas

• Aplica cursivas para
  • Términos en inglés poco comunes
  • Referencias y citas
  • Énfasis moderado en el texto

Términos técnicos

La industria del desarrollo web evoluciona constantemente junto con su vocabulario técnico. Estas pautas te ayudarán a manejar la terminología de manera efectiva y consistente.

Criterios para términos en inglés

• Mantén términos en inglés cuando su traducción
  • No tenga aceptación general en la comunidad
  • Pueda crear confusión o ambigüedad
  • Forme parte del vocabulario estándar
  • Aparezca en la documentación oficial

Introducción de términos técnicos

• Define cada término en su primera aparición
• Proporciona ejemplos prácticos cuando sea posible
• Incluye analogías para conceptos complejos
• Menciona el término en inglés junto a traducciones aceptadas

Consistencia y claridad

• Mantén el mismo término a lo largo del documento
• Evita usar variantes para un mismo concepto
• Actualiza el glosario con términos frecuentes
• Adapta las explicaciones al nivel de tu audiencia

Formato y presentación

• Usa cursivas para términos técnicos poco comunes
• Aplica negritas en conceptos clave nuevos
• Conserva el formato original de nombres propios
• Usa comillas para términos específicos o temporales

Bloques de información

Formato estándar

> [emoji] **Tipo de bloque**
> Contenido del bloque

Tipos de bloques

• 💡 Pro tip: consejos y mejores prácticas
• ⚠️ Advertencia: precauciones y casos especiales
• 🔍 Detalle técnico: profundización en conceptos
• ✨ Mejora: optimizaciones y características avanzadas

Títulos y encabezados

Formato y capitalización

• Usa Title Case para H1 (títulos principales)
  • Capitaliza todas las palabras significativas
  • Ejemplo: "Patrones de Diseño en React"
  • Ejemplo: "Gestión de Estado con Redux"
• Aplica Sentence case para H2 y siguientes
  • Solo capitaliza la primera palabra
  • Ejemplo: "Introducción al concepto"
  • Ejemplo: "Implementación básica"

Estructura y claridad

• Crea títulos concisos y descriptivos
• Evita lenguaje dramático o metafórico
• No uses puntuación al final del título
• Limita los títulos a 60 caracteres cuando sea posible

Jerarquía

• Utiliza H1 solo para el título principal del documento
• Mantén una estructura lógica de H2 para secciones principales
• Usa H3 y H4 para subsecciones
• No saltes niveles de encabezado

Ejemplos de jerarquía correcta

Arquitectura de Microservicios (H1)

Conceptos fundamentales (H2)

Patrones de comunicación (H3)

Gestión de datos (H3)

Implementación y despliegue (H2)

Contenedores y orquestación (H3)

Docker básico (H4)

Kubernetes (H4)

Ejemplos de código

// ✅ Ejemplo claro y conciso
interface User {
  name: string
  age: number
}

const UserProfile: React.FC<User> = ({ name, age }) => {
  return (
    <div>
      <h2>{name}</h2>
      <p>Edad: {age}</p>
    </div>
  )
}

// ❌ Evitar este formato
interface ComplexProps {
  data: any
  handlers: Record<string, Function>
  config?: Record<string, unknown>
}

Consideraciones de accesibilidad

• Agrega texto alternativo descriptivo a las imágenes
• Construye una jerarquía clara de encabezados
• Asegura alto contraste en los ejemplos de código
• Crea enlaces que describan su destino