Acerca de esta guía

Esta sección explica qué es la Guía de escritura del grupo, de dónde viene y cómo se usa. Cubre su origen (una adaptación de la guía de documentación de Google), la filosofía que hereda, un resumen de una página con las reglas que más se consultan, la relación con la norma de prosa de la casa (core/prosa/NORMA.md) y el registro de cambios. Si solo tienes cinco minutos, lee Lo esencial en una página.

Qué es y de dónde viene

La Guía de escritura es el estilo de documentación del grupo: CIS, CDS y COCHID. Aplica a toda la documentación que el grupo publica o mantiene: el manual de operación de vps-cis, los README de cis-admin y cochid-datos, la referencia de API de datos.cochid.cl, las pantallas y mensajes de error de las aplicaciones, el archivo societario y los documentos que emite cis-verify.

La guía tiene diez secciones, nueve de reglas y esta. Cada sección vive en un archivo de cis-style/galeria/escritura/ y tiene un submenú con anclajes estables (#t1, #t2...), de modo que una regla se puede citar por URL.

De dónde viene

La guía es una adaptación al español y a las convenciones del grupo de la Google developer documentation style guide, publicada bajo licencia CC BY 4.0. La adaptación se hizo el 20 de agosto de 2026 sobre la versión de la fuente vigente ese día (último cambio publicado por Google: 7 de julio de 2026). La guía de Google se eligió por tres razones: es la guía de documentación técnica más completa con licencia abierta, sus reglas están escritas para que las aplique gente que no es editora de oficio, y lleva nueve años de revisiones públicas con registro de cambios.

Adaptar no es traducir. Cada sección se tradujo completa (todas las reglas, todos los ejemplos) y después se le aplicaron cuatro transformaciones:

• Lo propio del inglés se reemplazó por la regla equivalente del español. Los artículos a y an pasaron a ser los apócopes (un buen día, el primer paso); las contracciones inglesas, a las contracciones al y del; el Title Case, a la minúscula de oración; las comillas inglesas, a las angulares «»; la coma serial, a la regla española de no poner coma antes de la y que cierra una enumeración.
• Números y fechas van en formato es-CL. Miles con punto (1.215.716), decimales con coma (0,62), fechas 20-08-2026 o «20 de agosto de 2026», hora de 24 h (14:30).
• Las reglas de la casa que van más lejos que Google se dicen explícitas y ganan. Cero raya (Google la permite; acá no), nunca voseo, tildes y ñ siempre, sin muletillas de IA, datos antes que interpretación. Cada una cita la regla de la norma de prosa por su id (P01 a P37).
• Los ejemplos de producto de Google se cambiaron por los del grupo. Donde la fuente dice Cloud Storage o Android, esta guía dice cis-admin, cochid-datos, el manual de operación o el archivo societario. Los dominios de ejemplo son los del grupo, no example.com.

Qué documentos la acompañan

La guía no está sola. Cuatro documentos del workspace regulan la escritura, cada uno con un trabajo distinto:

La guía está pensada para dos lectores: la persona que escribe o revisa documentación del grupo, y el agente que la genera. Para el segundo, el hook prosa-check.sh aplica las reglas bloqueantes de la norma en cada escritura; esta guía cubre lo que ningún hook verifica.

Filosofía

Esta sección recoge algunos de los principios y la filosofía detrás de la guía. Es una traducción de la página Philosophy of this style guide de Google, con dos ajustes que se señalan en su lugar.

Propósito

Esta guía codifica y registra las decisiones de estilo del grupo y describe el estilo de la casa. La guía no pretende ser objetivamente correcta.

Esta guía no pretende:

• Fijar un estándar de documentación para la industria.
• Competir con otras guías de estilo conocidas.
• Reemplazar la norma de prosa de la casa. Google dice aquí «reemplazar otra guía de estilo que ya sigas»; en el grupo la otra guía tiene nombre y precedencia: donde esta guía y core/prosa/NORMA.md difieren, manda la norma.
• Dar un conjunto completo de pautas básicas de redacción.
• Dar asesoría legal. Para asesoría legal, consulta a un abogado.

Nota: dos advertencias. Primera, lo que dice esta guía no limita los cambios que el grupo puede hacer en su documentación. Segunda, si no lees una pauta, sigues siendo responsable de documentar de forma ética y conforme a la ley.

Por qué no explicamos las razones

En general no explicamos el razonamiento detrás de la mayoría de las pautas. Hay un par de razones para eso:

• Muchas de las decisiones vienen de la accesibilidad, la localización, la audiencia global y la facilidad de comprensión. Dar esas razones como explicación en cada lugar donde aplican sería repetitivo.
• Muchas veces una pauta es una opción buena entre varias; en esos casos, a veces solo elegimos una por consistencia.
• Demasiada explicación recarga la página. El lector casi siempre quiere una respuesta breve a una pregunta concreta, no una explicación detallada.

Dicho esto, a veces sirve saber por qué se tomó una decisión, así que incluimos explicaciones ocasionales en Novedades.

El segundo ajuste respecto de la fuente: las reglas que vienen de la norma de prosa sí traen su razón, porque la norma la trae. Cada una de sus 37 reglas cita una fuente (ASD-STE100, el Español Técnico Simplificado de Gobbi, ISO 24495-1:2023, Orwell 1946, el catálogo de señales de escritura IA de Wikipedia) y tiene un detector mecánico en prosa-lint. Cuando una pauta de esta guía coincide con una regla de la norma, la guía cita el id (P05, P06, P37...) y el lector puede ir a la norma a leer el porqué.

Lo esencial en una página

La guía cubre mucho material, así que esta página resume sus puntos más importantes. Para más información sobre cada tema, sigue los enlaces. Es la traducción de Highlights de Google, con los enlaces apuntando a las secciones de esta guía y con un bloque final de reglas que la casa agrega.

Tono y contenido

• Escribe de forma cercana y cordial sin caer en lo frívolo.
• No anuncies nada por adelantado en la documentación.
• Usa texto de enlace descriptivo.
• Escribe de forma accesible.
• Escribe para una audiencia global.

Lenguaje y gramática

• Usa la segunda persona: «tú», no «nosotros». Y tú, nunca vos (P06).
• Usa la voz activa: deja claro quién hace la acción (P23).
• Usa la ortografía y la puntuación del español normativo, con las preferencias de Chile: tildes y ñ siempre, signos de apertura (¿ ¡), comillas angulares «» en prosa. La fuente dice aquí «ortografía estadounidense estándar»; la regla equivalente es la de la RAE y la Asociación de Academias.
• Pon las condiciones antes de las instrucciones, no después.
• Para el uso y la grafía de palabras concretas, consulta la lista de palabras.

Formato, puntuación y organización

• Usa minúscula de oración en títulos de documento y encabezados de sección (P37). Ver también Mayúsculas.
• Usa listas numeradas para secuencias.
• Usa listas con viñetas para casi todas las demás listas.
• Usa listas de descripción para pares de datos relacionados.
• No pongas coma antes de la «y» que cierra una enumeración. La fuente pide aquí la coma serial del inglés; en español no se usa.
• Pon el texto relacionado con código en fuente de código.
• Pon los elementos de UI en negrita.
• Usa un formato de fecha sin ambigüedad: 20-08-2026 o «20 de agosto de 2026», nunca 08/20/2026; hora de 24 h.

Imágenes

• Entrega texto alternativo.
• Entrega imágenes de alta resolución o vectoriales cuando sea práctico.

Lo que la casa agrega

Estas reglas no están en la fuente o van más lejos que ella. Vienen de core/prosa/NORMA.md y de CANON.md, y ganan sobre cualquier pauta de la guía que diga otra cosa.

• Cero raya (P05). Ni en prosa, ni en títulos, ni en UI, ni en código generado. Para separar incisos usa «·», paréntesis, «y», «hasta» o punto y oración nueva. Google permite la raya; acá no. Ver Rayas y guiones.
• Español neutro, tú (P06). Imprime, puedes, vuelve. Nunca el voseo rioplatense (imprimí, podés, volvé).
• Tildes y ñ siempre. También en código, nombres de archivo legibles, asuntos de correo y cadenas de UI. El transporte es UTF-8; si una capa las pierde, la capa está mal.
• Sin muletillas de IA (P01), sin antítesis retórica (P02), sin nominalizaciones (P03), sin adjetivos de marketing (P04). El hook bloquea la escritura que las contiene.
• Datos antes que interpretación. La cifra o el hecho van primero; la lectura, después. Lo accionable sube al inicio del documento (sección «Juicio» de la norma).
• Números y fechas es-CL. Miles con punto, decimales con coma, fecha día-mes-año, hora de 24 h, unidades con espacio (128 ms, 4 GB).
• Score prosa-lint menor que 1,0 violaciones por 100 palabras, 0 bloqueantes, en cualquier documento que se publique.

Cómo se relaciona con la norma de prosa

El grupo tiene dos documentos de escritura y cada uno hace un trabajo distinto. La norma de prosa clara (core/prosa/NORMA.md, versión 2) regula la forma de toda la prosa en español: informes, documentación, README, correos, mensajes de error y textos de interfaz. Son 37 reglas numeradas (P01 a P37), cada una con nombre, tier y detector mecánico, más una sección de juicio que aplica el revisor. La Guía de escritura regula la organización de la documentación: cómo se nombran los elementos de una interfaz, cómo se formatea un comando, una fecha, una lista, un enlace o un nombre de archivo. La norma dice qué no escribir; la guía dice cómo ordenar lo que sí escribes.

Precedencia

Donde esta guía y la norma difieren, manda la norma. La diferencia aparece en pocos lugares, porque la guía ya se adaptó a la norma al traducirla, pero aparece. El caso típico es la raya: la fuente la permite como signo de inciso y la norma la prohíbe sin excepción (P05). La sección Rayas y guiones de esta guía ya dice que no se usa; si encuentras otra sección que la admita, es un error de la guía y la norma gana.

La cadena completa de precedencia, de mayor a menor, es: CONSTITUTION.md, los ADR, CANON.md, core/prosa/NORMA.md, esta guía. La norma misma admite una válvula de escape: si cumplir una regla te obliga a escribir una barbaridad, rómpela y deja prosa-ok: <razón> en la línea (sexto principio de Orwell).

Dónde se tocan

Varias secciones de la guía tratan lo mismo que una regla de la norma. En esos casos la sección cita el id y la norma tiene la última palabra sobre el alcance. Esta tabla es el mapa:

Los dos modos y qué secciones caen en cada uno

La norma tiene dos modos y la guía hereda la división. En modo prosa (el default) se escriben los informes, la documentación conceptual, los README y los correos: rigen P01 a P23, con tope de 40 palabras por oración y 8 oraciones por párrafo. En modo estricto se escriben los procedimientos, los runbooks, los mensajes de error y los textos de interfaz: se suman P25 a P32, el tope baja a 25 palabras y 6 oraciones. En esta guía, las secciones Procedimientos, Notas y avisos, Elementos de UI e interacción y Sintaxis de línea de comandos describen texto que se escribe en modo estricto.

Herramientas

La norma se aplica con tres herramientas y la guía no tiene ninguna propia: lo que la guía regula se revisa a ojo.

• prosa-lint archivo.md da el reporte completo y el score. prosa-lint --modo estricto para procedimientos; prosa-lint --texto "una frase" para una prueba rápida.
• El hook prosa-check.sh corre en cada escritura de un archivo .md, .txt, .tex o .html en español y detiene la edición si aparece una regla del tier «bloquea». Esta misma página pasó por él; los ejemplos «No recomendado» que contienen muletillas llevan un comentario prosa-ok: ejemplo para que el hook los deje pasar.
• El skill /prosa <archivo> hace el pase editorial completo: la mecánica del linter más el juicio (datos primero, sin vueltas, un tema por párrafo, sustancia).

La configuración por repositorio vive en .prosa.json: modo, umbral, glosario, palabras prohibidas, frases propias y reglas desactivadas. El glosario de ese archivo y la Lista de palabras de esta guía deben coincidir; si una palabra está en uno y no en el otro, el que manda es el .prosa.json, porque es el que se verifica.

Cómo citar una regla

Cita las reglas de la norma por su id y las de la guía por URL con anclaje. El id es estable entre versiones de la norma y el linter lo imprime en cada hallazgo; el texto de la regla puede cambiar.

Novedades

Esta página resume los cambios significativos de la guía. Hereda el formato de la página What's new de Google: entradas por fecha, de la más reciente a la más antigua, con una tabla de dos columnas (el cambio y la página donde vive). Cuando una decisión tiene una razón que vale la pena conocer, la razón va aquí y no en la página de la regla (ver Por qué no explicamos las razones).

La adaptación se basa en la versión de la guía de Google publicada el 20 de agosto de 2026, cuya última entrada es del 7 de julio de 2026. Las dos entradas de 2026 de la fuente se traducen más abajo porque sus cambios ya están incorporados en esta guía. El historial anterior de la fuente (172 entradas, desde el 8 de junio de 2017) queda en la página original y no se reproduce aquí.

20 de agosto de 2026

Creación de la guía. Traducción completa de las nueve secciones de la guía de Google y adaptación al español de Chile y a las convenciones del grupo.

Cambios recientes de la fuente ya incorporados

Las dos entradas de 2026 de la guía de Google, traducidas. La columna «Página» apunta a la sección equivalente de esta guía. Donde la fuente cambió una entrada de su lista de palabras que no existe en el glosario de la casa, se indica.

7 de julio de 2026 (fuente)

7 de abril de 2026 (fuente)

Adaptación al español y a las convenciones del grupo de la Google developer documentation style guide, publicada bajo CC BY 4.0. Donde esta guía y la norma de prosa de la casa difieren, manda la norma (core/prosa/NORMA.md).