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 que coincidan con ella. No necesita 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. Escriba para un lector que está cansado, tiene prisa, lee en un segundo idioma o es nuevo en el stack. Sirva a ese lector por encima de todo lo demás.

Legibilidad

Prefiera:

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

Documente cómo construir con EmDash, no cómo está construido EmDash. Los detalles de implementación pertenecen a los documentos solo cuando cambian una decisión que el lector debe 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), enlace a una fuente confiable en lugar de explicarlos. Documente 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 resistir activamente:

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

• Prominencia del constructor sobre prominencia del lector. Las decisiones de arquitectura y diseño internas que fueron significativas para tomar son generalmente invisibles e irrelevantes para usar. Indique 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 no necesita conocer el lenguaje del analizador. Si el mecanismo realmente ayuda a alguien que trabaja en EmDash, pertenece al documento de internals, no a una página de cara al usuario.

• Autodefinición por hombre de paja. No defina EmDash por contraste con una caricatura de otras herramientas (“A diferencia de la mayoría de los CMS…”, “Los CMS tradicionales lo obligan a…”, “en muchos CMS declara X en código”). Describa lo que hace EmDash, directamente, y déjelo destacar 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 y compensaciones concretas, no un hombre de paja que se invite al lector a no gustarle.

• Definición por negación. Enmarcar una capacidad como el trabajo que no tiene que hacer (“sin migración que escribir”, “sin reconstrucción”, “sin tocar código”, “sin servicio separado”) es un hombre de paja disfrazado: solo funciona para un lector que lleva la alternativa que ha inventado para ellos. Indique lo que el lector hace y lo que sucede. “Agregue un campo en el panel de administración; surte efecto inmediatamente”, no “agregue un campo sin migración, sin reconstrucción, 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 reconstrucciones” es el mismo hecho expresado como el dolor ausente de otra persona: prefiera el primero.

La prueba para cualquier oración: ¿estaría peor un lector que intenta terminar su tarea si se eliminara? Si no, elimínela. Si solo tiene sentido para un lector que compara EmDash con otra cosa, está en el lugar equivocado o debe eliminarse.

Siempre actual, no changelog

Las páginas de cara al usuario describen cómo funciona EmDash ahora, para un lector que no tiene una 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 viven solo en una guía de actualización. Que un concepto se introdujo recientemente nunca es una razón para mencionar que es reciente.

Voz y tono

Escriba oraciones neutrales y fácticas. Indique los hechos directamente.

✅ Los plugins se ejecutan en un tiempo de ejecución aislado y solo pueden acceder a las APIs que declaran.

❌ ¡Los plugins viven en una pequeña sandbox acogedora donde nunca puede pasar nada malo!

• No use nosotros, nos, nuestro o vamos. No está sentado con el lector. Reformule para dirigirse al lector directamente o describir el sistema.
• Nunca use yo. La documentación no trata sobre el autor.
• Diríjase al lector como usted cuando sea necesario, especialmente para señalar un paso donde algo puede salir mal.
• No narre ni cuente una historia. Sin “ahora que hemos configurado X, pasemos a Y”. Comience una sección con el objetivo, luego los pasos.
• Evite caprichos, mascotas y referencias culturales. Agregan esfuerzo de lectura y no se traducen.
• Los signos de exclamación son raros. Use uno solo para algo genuinamente alentador o sorprendente. Cuando tenga dudas, use un punto.

Encabezados

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

Listas

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

Ejemplos

• “por ejemplo” completo 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 todas las opciones no es una lista de ejemplos: use paréntesis sin “p. ej.” (las propiedades requeridas (src, alt)).

Ejemplos de código

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

Introduzca 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 comience con un fragmento de oración que termina en dos puntos, un encabezado desnudo o “así:”.

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

❌ Agregue el plugin así:

La introducción prepara al lector para lo que hace el código, por lo que solo necesita averiguar 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 (“Agregue un tsconfig.json:” seguido del archivo está bien en un paso numerado).

Otras reglas:

• Use código real y funcional. Sin foo/bar. Muestre una configuración realista, no todos los valores posibles: el lector solo tendrá uno.

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

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

• Use anotaciones de Expressive Code, no vallas ```diff sin formato, para cambios antes/después. Marque líneas cambiadas con del={n} / ins={n} o texto cambiado con del="…" / ins="…". Mantenga los diffs mínimos y locales a las líneas que cambian.

  El siguiente ejemplo muestra una sola línea cambiando:

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

• Previsualice 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 escatime en ellas.

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

Luego enumere cada cambio importante como su propia entrada:

### [Renamed/Changed/Removed/Deprecated]: <feature>

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

Elija el verbo según cómo el lector sienta el impacto. Si un nuevo valor predeterminado reemplaza su valor, eso es un “Changed: default value”, no un “Added: option”.

Un cambio importante es uno que requiere un cambio en el proyecto del lector o deja de funcionar. Dé la acción, no solo el hecho. No “la versión mínima de Node.js ahora es X” sino “verifique su versión de Node.js con el siguiente comando y actualice si está por debajo de X”.

Específicos de EmDash

Convenciones para situaciones recurrentes, ordenadas por la frecuencia con que un contribuyente las encuentra. Esta es una lista de convenciones, no una clasificación de qué características importan.

Plugins: sandboxed vs native

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

Localización

No incluya cambios de messages.po en un PR de documentación. Un flujo de trabajo extrae catálogos al fusionar con main. Incluirlos crea agitación y conflictos de fusión.

Características experimentales

Una característica detrás de una bandera experimental, o un formato de cable inestable bajo un RFC, puede cambiar sin previo aviso. Mantenga su documentación ligera, márquela con un <Aside> de precaución y apunte al RFC o discusión como la fuente de verdad. No documente una superficie inestable con detalle exhaustivo.

Cuentas de Atmosphere

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

Los documentos son 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 coincidentes en otra parte del sitio. Cambios pequeños, revisados y consistentes mantienen todo el sitio coherente.