Guía de estilo de documentación

Esta guía define cómo se escribe la documentación de EmDash. Las contribuciones se editan para ajustarse a ella. No necesitas memorizarla — los revisores y editores ayudarán — pero seguirla hace que una contribución se fusione más rápido.

La documentación existe para ayudar a alguien a hacer algo y luego volver a su proyecto. Escribe para un lector que está cansado, con prisa, leyendo en un segundo idioma o nuevo en el stack. Sirve a ese lector por encima de todo.

Legibilidad

Prefiere:

• Oraciones cortas y párrafos cortos.
• Vocabulario sencillo sobre jerga.
• Abreviaciones y acrónimos escritos completos la primera vez.
• Encabezados y listas para dividir pasajes largos.
• Voz activa.

Documenta cómo construir con EmDash, no cómo está construido EmDash. Los detalles de implementación pertenecen a la documentación solo cuando cambian una decisión que el lector tiene que tomar (cuándo elegir un valor no predeterminado, una advertencia que afecta su proyecto). Nunca reemplazan un ejemplo de uso.

Para temas que no son de EmDash — TypeScript, el AT Protocol, fuentes web, SQL — enlaza a una fuente confiable en lugar de explicarlos. Documenta lo que alguien necesita saber para usar la función en EmDash.

Qué enfatizar

El énfasis de una página debe estar determinado por lo que el lector necesita para hacer su tarea, nunca por lo que fue interesante o reciente para las personas que construyeron EmDash. Tres hábitos a los que resistirse activamente:

• Peso por recencia de autoría. Que una decisión sea nueva, o esté fresca en la mente del escritor, no es razón para destacarla. Lo más cambiado raramente es lo más importante para un lector. Ordena secciones, elementos de lista y titulares por la frecuencia con que un lector los necesita, no por cuándo se agregaron. Si estás documentando algo porque acaba de cambiar, probablemente estás escribiendo una entrada de changelog, no documentación.

• Relevancia del constructor sobre relevancia del lector. La arquitectura interna y las decisiones de diseño que fueron significativas de tomar son generalmente invisibles e irrelevantes de usar. Indica la capacidad que obtiene el lector, no el mecanismo detrás de ella. Un lector que define una colección no necesita saber dónde se almacena el esquema, así como tampoco necesita saber el lenguaje del parser. Si el mecanismo genuinamente ayuda a alguien trabajando en EmDash, pertenece a la documentación interna, no a una página orientada al usuario.

• Autodefinición por hombre de paja. No definas EmDash por contraste con una caricatura de otras herramientas (“A diferencia de la mayoría de los CMS…”, “Los CMS tradicionales te obligan a…”, “en muchos CMS declaras X en código”). Describe lo que EmDash hace, directamente, y deja que se sostenga por sí mismo. La comparación solo se permite cuando la comparación es la propia pregunta del lector: en la página de evaluación y las páginas de orientación “Viniendo de…”. Incluso allí debe ser específica y justa — comportamientos concretos y compromisos, no un hombre de paja que se invita al lector a rechazar.

• Definición por negación. Enmarcar una capacidad como el trabajo que no tienes que hacer — “sin migración que escribir”, “sin rebuild”, “sin tocar código”, “sin servicio separado” — es un hombre de paja disfrazado: solo funciona para un lector que carga la alternativa que has inventado para él. Indica lo que el lector hace y lo que sucede. “Agrega un campo en el panel de administración; surte efecto inmediatamente” — no “agrega un campo sin migración, sin rebuild, sin código”. La excepción es un comportamiento concreto, relevante para el lector, expresado positivamente: “el contenido se sirve en tiempo de ejecución, por lo que las ediciones aparecen inmediatamente” es un hecho sobre EmDash; “no se necesitan rebuilds” es el mismo hecho expresado como el dolor ausente de alguien más — prefiere lo primero.

La prueba para cualquier oración: ¿estaría peor un lector tratando de terminar su tarea si se eliminara? Si no, elimínala. Si solo tiene sentido para un lector comparando EmDash con otra cosa, está en el lugar equivocado o debería ser eliminada.

Perenne, no changelog

Las páginas orientadas al usuario describen cómo funciona EmDash ahora, para un lector que no tiene ninguna versión anterior en su cabeza. Sin “ahora”, “ya no”, “solía”, “en lugar del antiguo”, “esto cambió”. Las diferencias de versión a versión solo viven en una guía de actualización. Que un concepto haya sido introducido recientemente nunca es razón para mencionar que es reciente.

Voz y tono

Escribe oraciones neutrales y factuales. Indica los hechos directamente.

✅ Los plugins se ejecutan en un runtime aislado y solo pueden acceder a las APIs que declaran.

❌ ¡Los plugins viven en un pequeño sandbox acogedor donde nada malo puede pasar nunca!

• No uses nosotros, nos, nuestro ni hagamos. No estás sentado con el lector. Reformula para dirigirte al lector directamente o describir el sistema.
• Nunca uses yo. La documentación no trata sobre el autor.
• Dirígete al lector como tú cuando sea necesario, especialmente para señalar un paso donde algo puede salir mal.
• No narres ni cuentes una historia. Sin “ahora que hemos configurado X, pasemos a Y”. Comienza una sección con el objetivo, luego los pasos.
• Evita el humor, mascotas y referencias culturales. Agregan esfuerzo de lectura y no se traducen.
• Los signos de exclamación son raros. Usa uno solo para algo genuinamente alentador o sorprendente. En caso de duda, usa un punto.

Encabezados

• El título de la página es el <h1> (del frontmatter title). Las secciones comienzan en <h2>.
• Mantén los encabezados cortos. <h2> y <h3> aparecen en la barra lateral “En esta página”; previsualízalo y acorta cualquier cosa que se desborde.
• Sin puntuación final, incluyendo dos puntos.
• Formatea el código como <code> en encabezados igual que en el texto del cuerpo.

Listas

• Usa una lista con viñetas cuando el orden no importa, como un conjunto de opciones o propiedades.
• Usa una lista numerada para pasos que deben seguirse en secuencia. Usa el componente <Steps> de Starlight para procedimientos.
• Cuando los elementos de la lista crecen a múltiples párrafos o llevan varios términos de código, cambia a secciones <h3> en su lugar.

Ejemplos

• “por ejemplo” en su forma completa introduce un solo ejemplo o hipotético.
• “p. ej.” dentro de paréntesis introduce una lista no exhaustiva (p. ej. GitHub, GitLab).
• Una lista que cubre cada opción no es una lista de ejemplos — usa paréntesis sin “p. ej.” (las propiedades requeridas (src, alt)).

Capturas de pantalla

Usa una captura de pantalla solo cuando clarifica materialmente las relaciones espaciales, un estado de interfaz o la ubicación de controles. Mantén las instrucciones y otra información esencial en el texto para que la página siga siendo utilizable sin la imagen.

Cada captura de pantalla debe ser actual y tomada para el propósito específico de la página. Proporciona texto alternativo que describa la pantalla y el estado relevante. Registra el fixture, la ruta, el viewport, el locale y el tema para que otro contribuidor pueda reproducir la captura.

Ejemplos de código

Los ejemplos de código son tan importantes como la prosa que los rodea.

Introduce cada bloque de código con una oración completa e independiente en su propia línea, diciéndole al lector qué hace el bloque. No comiences con un fragmento de oración que termine en dos puntos, un encabezado desnudo o “así:”.

✅ El siguiente ejemplo registra un plugin en el array sandboxed:

❌ Agrega el plugin así:

La introducción prepara al lector para qué hace el código, de modo que solo necesita descubrir cómo. También crea un patrón de rellenar espacios en blanco para un lector que hace algo ligeramente diferente.

Dentro de un procedimiento <Steps>, una instrucción imperativa directa es la introducción (“Agrega un tsconfig.json:” seguido del archivo está bien en un paso numerado).

Otras reglas:

• Usa código real y funcional. Sin foo/bar. Muestra una configuración realista, no todos los valores posibles — el lector solo tendrá una.

• Agrega un nombre de archivo title= a cualquier bloque que represente un archivo, para que el lector sepa dónde va el código.

  ```ts title="src/plugin.ts"

• Usa anotaciones de Expressive Code, no cercas ```diff crudas, para cambios antes/después. Marca líneas cambiadas con del={n} / ins={n} o texto cambiado con del="…" / ins="…". Mantén los diffs mínimos y locales a las líneas que cambian.

  El siguiente ejemplo muestra un cambio de una sola línea:

  ```ts del={1} ins={2}
  import { definePlugin } from "emdash";
  import type { SandboxedPlugin } from "emdash/plugin";
  ```

• Previsualiza el código renderizado localmente antes de enviar. Un error tipográfico puede romper la visualización.

Guías de actualización y migración

Una guía que ayuda a un lector a mover un proyecto existente a una nueva versión sigue una estructura fija. Las secciones “¿Qué debo hacer?” son la parte que los lectores más valoran — no escatimes en ellas.

Abre con: cómo actualizar, una nota de que las cosas pueden “simplemente funcionar” pero que sigan leyendo si no, y un enlace al changelog.

Luego lista cada cambio que rompe compatibilidad como su propia entrada:

### [Renombrado/Cambiado/Eliminado/Obsoleto]: <característica>

En versiones anteriores, <una oración, tiempo pasado, qué hacía>.

<Una oración, tiempo presente, cómo funciona ahora>.

#### ¿Qué debo hacer?

<Acciones imperativas: Actualizar… / Reemplazar… / Eliminar…, con un diff mínimo.>

Elige el verbo según cómo el lector siente el impacto. Si un nuevo valor predeterminado reemplaza su valor, eso es un “Cambiado: valor predeterminado”, no un “Agregado: opción”.

Un cambio que rompe compatibilidad es uno que requiere un cambio en el proyecto del lector o deja de funcionar. Da la acción, no solo el hecho. No “la versión mínima de Node.js es ahora X” sino “verifica tu versión de Node.js con el siguiente comando y actualiza si está por debajo de X”.

Especificidades de EmDash

Convenciones para situaciones recurrentes, ordenadas por la frecuencia con que un contribuidor las encuentra. Esta es una lista de convenciones, no un ranking de qué características importan más.

Plugins: sandboxed vs nativos

Los plugins sandboxed y nativos son formatos diferentes con diferentes formas de autoría. Un cambio en uno raramente afecta al otro. Indica qué formato trata una página o ejemplo. Al editar una página de plugin sandboxed, no cambies ejemplos de plugins nativos, y viceversa.

Localización

No incluyas cambios de messages.po en un PR de documentación. Un flujo de trabajo extrae catálogos al fusionar a main. Incluirlos crea churn y conflictos de merge.

Características experimentales

Una característica detrás de un flag experimental, o un formato wire inestable bajo un RFC, puede cambiar sin previo aviso. Mantén su documentación ligera, márcala con un <Aside> de precaución y apunta al RFC o discusión como la fuente de verdad. No documentes una superficie inestable en detalle exhaustivo.

Cuentas Atmosphere

Cuando la identidad portable, propiedad del usuario, detrás de Bluesky y la red más amplia del AT Protocol aparezca, llámala una cuenta Atmosphere y usa ese término consistentemente. Enlaza la primera mención a la guía de inicio de sesión Atmosphere o atmosphereaccount.com. did:plc:… y los handles son sus identificadores concretos; úsalos donde se necesite un valor literal.

La documentación es código

El sitio de documentación es un proyecto Astro adyacente a EmDash. Los cambios de documentación pasan por el mismo flujo de pull request y revisión que el código. Cada cambio de texto espera una revisión; un cambio de redacción puede cambiar el significado de una oración o necesitar ediciones correspondientes en otro lugar del sitio. Cambios pequeños, revisados y consistentes mantienen todo el sitio coherente.