cis-style · hub

Nombres y nomenclatura

Esta sección cubre cómo se nombran las cosas en la documentación del grupo. Qué dominios, correos, personas, teléfonos y direcciones se usan en los ejemplos para no exponer datos reales. Cómo se escriben los nombres de archivo y cómo se habla de los tipos de archivo. Cómo se tratan las marcas registradas de terceros. Y cómo se escriben los nombres de las sociedades, marcas, productos y servicios del grupo. Las reglas vienen de la guía de Google y se adaptan al español y a la casa. Los nombres de ejemplo sirven para una audiencia global, las direcciones y los formatos siguen la convención es-CL, y el registro de nombres del grupo es core/core-style/ESTRUCTURA.md.

Dos reglas de la norma de prosa atraviesan toda la sección. Cero raya (P05: se usa «·», «y», «hasta», paréntesis o punto y oración nueva; la raya solo aparece acá dentro de ejemplos no recomendados). Un significante, un significado (P07): cada sociedad, marca y producto del grupo tiene un solo nombre canónico y la documentación no lo rota con sinónimos ni apodos.

Dominios y nombres de ejemplo

No uses dominios, direcciones de correo ni nombres de personas reales en los ejemplos. No reveles información personal identificable (PII): dominios, correos, teléfonos, nombres de personas, nombres de proyecto, RUT ni números de tarjeta. En su lugar, usa ejemplos imaginarios (ficticios) o marcadores de posición como ID_USUARIO o CORREO.

Los dominios y servicios reales del grupo (innovacionsantiago.cl, cochid.cl, circulodesantiago.cl) aparecen en la documentación cuando hablas de ese servicio real. Nunca los uses como disfraz de un actor ficticio: si el ejemplo necesita un cliente inventado, el cliente vive en example.com.

Dominios de ejemplo

Cuando necesites un dominio genérico en un ejemplo, usa example.com, example.org o example.net. La Internet Assigned Numbers Authority (IANA) reserva esos dominios para documentación: nadie los puede registrar, así que ningún lector termina en un sitio ajeno.

Google usa además dominios propios reservados para su documentación (altostrat.com, cymbalgroup.com y otros). Son de Google, no del grupo: no los uses. La casa no reserva dominios de ejemplo propios; los tres de la IANA bastan.

Si necesitas un dominio internacionalizado (con caracteres fuera de ASCII), usa uno de los dominios de prueba IDN y copia la columna «URL of the test site».

Recomendado Los nombres de host con caracteres fuera de ASCII se codifican en Punycode. Por ejemplo, http://مثال.إختبار se codifica como xn--kgbechtv.
No recomendado Los nombres de host con caracteres fuera de ASCII se codifican en Punycode. Por ejemplo, http://compañía.cl se codifica como xn--compaa-7va5a.cl.

Direcciones de correo de ejemplo

Si necesitas un correo genérico, combina uno de los dominios de ejemplo con uno de los nombres de persona de ejemplo: dana@example.com. Las direcciones genéricas de rol, como soporte@example.net, también sirven. No uses nombres de personas reales, nombres de producto ni nombres inventados fuera de la lista en una dirección de correo.

Recomendado Escribe a dana@example.com para pedir acceso.
El aviso llega a soporte@example.net.
No recomendado Escribe a dana@innovacionsantiago.cl para pedir acceso (dominio real del grupo para un actor ficticio).
El aviso llega a cis-admin@example.net.
El aviso llega a pepito@example.net.

Nombres de persona de ejemplo

Cuando necesites nombres de pila de ejemplo, toma los de esta lista. Está armada para una audiencia global: son nombres cortos, de orígenes variados y, en su mayoría, sin género marcado en español.

Apellidos de ejemplo

Cuando necesites un apellido, usa una inicial después del nombre de pila: Quinn N. o Dana A. Así no inventas apellidos que coincidan con personas reales.

Recomendado Dana A. aprueba el asiento y Quinn N. lo contabiliza.
No recomendado Juan Pérez aprueba el asiento y María González lo contabiliza.

Más sobre las personas de ejemplo

Cuando escribes sobre personas, incluso ficticias o hipotéticas, tu texto lo leen personas reales que quieren sentirse respetadas y bienvenidas. Tu audiencia incluye personas con distintos trabajos, contextos culturales y orígenes, así que incluye variedad en los ejemplos.

El inglés resuelve el género con el pronombre neutro they. El español no tiene esa salida y la casa ya fijó la suya en Lenguaje inclusivo. Reformula alrededor del género («la persona que aprueba», «quien administra», segunda persona o infinitivo). No uses formas dobladas ni la arroba, la equis o la «e» como marca. No especifiques el género salvo que sea parte de la información. Evita ejemplos que dependan de un binario de género. Si un ejemplo exige marcar género, ten presente que varios nombres de la lista sugieren un género en un idioma o cultura concretos; revisa que el nombre elegido no cargue una connotación contradictoria.

Cuida las suposiciones y los estereotipos que un ejemplo hipotético puede reforzar:

Recomendado Kai pide la cotización y Rosario, del área de finanzas, la aprueba en cis-admin.
No recomendado La secretaria pide la cotización y el gerente la aprueba en cis-admin.

Para casi toda la documentación usa los nombres de la lista anterior. Parte de la documentación de seguridad usa el elenco de Alice y Bob. No uses ese elenco salvo que documentes una especificación técnica que lo usa. Si lo usas, usa solo nombres de ese elenco.

Nombres de empresa de ejemplo

Cuando necesites una empresa en un ejemplo, usa Organización Ejemplo. Si necesitas distinguir dos empresas ficticias, agrega una descripción al nombre: Organización Ejemplo Grande y Organización Ejemplo Emergente.

Las sociedades del grupo (Compañía de Innovación de Santiago SpA, Círculo de Santiago SpA, Compañía Chilena de Inteligencia de Datos SpA) son reales y tienen RUT. Aparecen en la documentación cuando hablas de ellas; nunca hacen de cliente o proveedor inventado. Para un RUT de ejemplo usa un marcador de posición (RUT_EMPRESA, NN.NNN.NNN-D): la casa no reserva ningún RUT ficticio y un RUT inventado con dígito verificador válido puede pertenecer a alguien.

Recomendado Organización Ejemplo emite una factura a Organización Ejemplo Emergente con el RUT RUT_EMPRESA.
No recomendado Círculo de Santiago SpA emite una factura a Tienda de Pedro con el RUT 12.345.678-5.

Teléfonos de ejemplo

Casi todos los teléfonos de la documentación son ejemplos. Nunca uses un número real.

Chile no reserva un rango de números para ficción o documentación. Tienes dos salidas. La primera es un marcador de posición con el formato chileno (+56 9 NNNN NNNN para móvil, +56 2 NNNN NNNN para Santiago). La segunda, si el ejemplo necesita un número que parezca real, es el rango estadounidense reservado para ejemplos y ficción: del 800-555-0100 al 800-555-0199. Para el formato de los teléfonos, consulta Teléfonos.

Recomendado Llama al +56 9 NNNN NNNN del contacto de emergencia.
El soporte atiende en el +1 800-555-0142.
No recomendado Llama al +56 9 1234 5678 del contacto de emergencia (número inventado con formato válido: puede pertenecer a alguien).

Direcciones IP de ejemplo

Cuando necesites una dirección IPv4 en un ejemplo, por ejemplo en un registro, usa una de las direcciones que la RFC 5737 reserva para documentación:

Para rangos IPv4 usa estos ejemplos:

Cuando necesites una dirección IPv6, usa valores del rango de la RFC 3849. Algunos ejemplos:

Para rangos IPv6 usa este ejemplo:

Recomendado El registro de Caddy muestra la conexión desde 203.0.113.7.
No recomendado El registro de Caddy muestra la conexión desde 108.175.4.190.

La IP del servidor real del grupo aparece en el manual de operación porque ahí es el dato. En un ejemplo que ilustra un formato de registro, no.

Direcciones postales de ejemplo

Evita las direcciones reales en los ejemplos. El domicilio social del grupo es un dato real y no hace de ejemplo. Usa una de estas direcciones ficticias:

Recomendado Dirección de facturación: Avenida Ficticia 1234, oficina 56, Santiago.
No recomendado Dirección de facturación: [el domicilio social real del grupo].

Nombres de proyecto de ejemplo

Cuando necesites un nombre de proyecto de ejemplo, inventa uno con sentido o descriptivo. Asegúrate de que el nombre sirva en el entorno del lector. No uses componentes opacos como foo, bar y baz.

Cuando haga falta, agrega un esquema de numeración al final: staging, frontend-desarrollo, backend-desarrollo, produccion-1, produccion-2.

Recomendado Crea el proyecto padron-medicamentos-staging y luego padron-medicamentos-produccion-1.
No recomendado Crea el proyecto foo y luego foo2.

Identificadores de ejemplo

Cuando necesites un identificador numérico único en un ejemplo (una cuenta de servicio, un folio, una fila), usa 123456789012345678901. Es obviamente artificial y no coincide con ningún identificador real.

Recomendado La política muestra el identificador deleted:serviceAccount:mi-cuenta@mi-proyecto.iam.gserviceaccount.com?uid=123456789012345678901.
El asiento 123456789012345678901 queda en borrador hasta que lo apruebes.
No recomendado El asiento 604 queda en borrador hasta que lo apruebes.

Nombres de archivo

Esta sección cubre cómo se nombran los archivos y directorios nuevos y cómo se habla de los archivos y de los tipos de archivo en el texto.

Pautas para los nombres

Escribe los nombres de archivo y de directorio en minúscula, con la excepción ocasional por coherencia, para que las búsquedas sean más fáciles y los resultados más útiles. Por ejemplo, la mayoría de los sistemas operativos tipo Unix distinguen mayúsculas: no encuentran un archivo llamado Manual-Operacion.html si buscas manual-operacion.html. Linux y macOS los tratan como dos archivos distintos.

Usa guiones, no guiones bajos, para separar palabras: consultar-datos.html. Los buscadores interpretan los guiones en nombres de archivo y directorio como espacios entre palabras. Los guiones bajos en general no se reconocen, así que perjudican el posicionamiento.

Usa solo caracteres alfanuméricos ASCII en los nombres de archivo y directorio. Esta es la única parte de la casa donde las tildes y la eñe no van: la prosa las lleva siempre, el nombre del archivo nunca. Escribe guia-de-estilo.html, no guía-de-estilo.html. Escribe anio-2026.csv, no año-2026.csv.

No uses nombres de página genéricos como documento1.html.

Recomendado respaldo-lago-datos.md
acta-directorio-2026-08-20.pdf
No recomendado Respaldo_Lago_Datos.md
Acta Directorio 20-08-2026 (versión final).pdf
documento1.md

Cuando el nombre lleva fecha, usa el orden año-mes-día (2026-08-20): ordena bien alfabéticamente. El formato es-CL de la prosa (20-08-2026) no sirve en un nombre de archivo porque desordena los listados.

Excepciones por coherencia

Si agregas un archivo a un directorio donde todo lo demás ya usa guiones bajos y no es viable cambiar todo a guiones, está bien usar guiones bajos para mantener la coherencia.

Por ejemplo, si el directorio ya tiene leccion_1.md, leccion_2.md y leccion_3.md, está bien agregar el nuevo como leccion_4.md en vez de leccion-4.md. En cualquier otra situación usa guiones.

Recomendado evitar-cliches.md
A veces aceptable evitar_cliches.md
No recomendado evitarcliches.md
evitarCliches.md
evitar-clichés.md

Otras excepciones

Está bien cierta incoherencia en los nombres de archivo cuando no se puede evitar. Por ejemplo, a veces las herramientas que generan documentación de referencia producen nombres según otros requisitos de estilo o según el diseño y las convenciones de nombres del producto o la API. En esos casos, las excepciones para esos archivos están bien. Las migraciones de Alembic en cochid-datos (0113_catalogo_dipres.py) y los paquetes de Python, que exigen guion bajo, son dos ejemplos del grupo.

Referirse a archivos

Las secciones siguientes explican cómo se hace referencia a los archivos en el texto.

Referirse a nombres de archivo

Cuando te refieras a un archivo concreto:

Recomendado En el archivo build.sh siguiente, cambia los valores por defecto de todos los parámetros:
Edita el archivo Impersonate-Service-Accounts.html que genera la herramienta.
No recomendado En el build.sh siguiente, cambia los valores por defecto de todos los parámetros:
Edita el archivo impersonate-service-accounts.html que genera la herramienta (cuando el archivo real se llama Impersonate-Service-Accounts.html).

Referirse a interacciones con archivos

Cuando describas una interacción con archivos y tipos de archivo, no uses el tipo de archivo como verbo. El español fabrica esos verbos con facilidad («zipear», «pdfear», «excelear») y todos salen de la documentación.

Recomendado Extrae el contenido del archivo zip.
Exporta el balance a un archivo PDF.
No recomendado Deszipea el archivo.
Pdfea el balance.

Referirse a tipos de archivo

Cuando hables de un tipo de archivo, usa el nombre formal del tipo, no la extensión. (El nombre del tipo suele ir en mayúsculas porque muchos son siglas.) No uses la extensión para referirte genéricamente al tipo de archivo. En español el nombre del tipo se pospone al sustantivo: «un archivo PNG», «un archivo de Bash».

Recomendado un archivo PNG
No recomendado un archivo .png
Recomendado un archivo de Bash
No recomendado un archivo .sh

La tabla siguiente lista algunas extensiones y el nombre de tipo que corresponde usar.

ExtensiónNombre del tipo de archivo
.adocarchivo AsciiDoc
.csvarchivo CSV
.exearchivo ejecutable
.gifarchivo GIF
.imgarchivo de imagen de disco
.ipynbarchivo IPYNB (cuaderno de Jupyter)
.jararchivo JAR
.jpg, .jpegarchivo JPEG
.jsonarchivo JSON
.mdarchivo Markdown
.pdfarchivo PDF
.pngarchivo PNG
.psarchivo PostScript
.ps1archivo de PowerShell
.pyarchivo de Python
.sharchivo de Bash
.sqlarchivo SQL
.svgarchivo SVG
.tararchivo tar
.tfarchivo de Terraform
.tiffarchivo TIFF
.txtarchivo de texto
.typarchivo de Typst
.wasmarchivo Wasm
.yamlarchivo YAML
.ziparchivo zip

Dos notas sobre la tabla. La guía de Google asigna .ps a PowerShell; esa extensión es de PostScript, y los scripts de PowerShell llevan .ps1. Se agrega .typ porque el grupo compone documentos con Typst (la enciclopedia de Editorial Sebastián, las actas de cds-protocolo).

Marcas registradas

Sigue las pautas de uso que publica cada titular de una marca registrada.

Rotular los términos con marca registrada

Para marcar o atribuir una marca registrada en la documentación, sigue las pautas de uso que entrega el titular de cada marca. Cada titular decide si su marca lleva el símbolo ® o ™, dónde y cuántas veces; no hay una regla única. Si el titular no pide nada, no agregues símbolos por tu cuenta: la prosa del grupo no los lleva.

Para el caso de las marcas de Google, consulta About our trademarks and how to use them. Para las marcas del propio grupo, la fuente es cis/cis-style/brands/LOGOS-CANONICOS.md: se usan solo los logos canónicos y no se inventan ni regeneran. Para más información, consulta Marcas.

Usa las marcas solo como modificadores

Cuando uses un término con marca registrada, úsalo siempre para modificar un sustantivo, no como sustantivo por sí solo. No uses una marca como verbo.

Nunca formes un plural a partir de una marca ni la cambies de ninguna forma: ni diminutivos, ni derivados, ni adaptación ortográfica. El español no tiene posesivo con apóstrofo, así que la regla del inglés sobre Chromebook's se traduce en otra: la marca tampoco se declina ni se pluraliza con «-s» o «-es». Para más información, consulta Posesivos y Plurales.

Recomendado Otra opción es usar un computador portátil Chromebook.
No recomendado Otra opción es usar un Chromebook.
Recomendado Las funciones del computador Chromebook dependen de una conexión a internet.
No recomendado Las funciones de los Chromebooks dependen de una conexión a internet.
Recomendado Para más información sobre los computadores Chromebook, busca «computadores portátiles» en Google.
No recomendado Para más información sobre los computadores Chromebook, googlea «computadores portátiles».
Recomendado Envía el acta por la aplicación WhatsApp.
Abre la planilla en Excel.
No recomendado Whatsappea el acta.
Excelea los datos.

Para más información sobre el uso de las marcas de Google, consulta Rules for proper usage.

Nombres de producto del grupo

Esta sección explica cómo se escriben los nombres de las sociedades, marcas, productos, vistas y servicios del grupo. La fuente única de qué es cada cosa, quién es su dueño y quién la opera es core/core-style/ESTRUCTURA.md (Martín, 09-08-2026). Esta sección no repite ese registro: dice cómo se escribe lo que el registro nombra.

El registro y las clases

El registro distingue ocho clases, cada una con la prueba que la decide. Para escribir, importan cuatro:

Si no sabes en qué clase cae algo, consulta el registro antes de escribir. Un nombre que no está en el registro no existe para la documentación: no lo inventes, pide que lo agreguen.

Mayúsculas en los nombres de producto

En inglés, Google escribe sus nombres de producto en Title Case (cada palabra con mayúscula inicial). En español no existe esa convención y la norma la marca en los títulos (P37). La regla del grupo es más simple: cada nombre se escribe exactamente como el registro lo escribe, y esa forma oficial gana sobre cualquier regla general de mayúsculas. Para más información sobre las reglas generales, consulta Mayúsculas.

Cuando escribas sobre cualquier producto, propio o de terceros, sigue la capitalización oficial de marcas, empresas, software, productos, servicios, funciones y términos que definen las empresas y las comunidades de código abierto.

Nombres de función

Una función es un atributo o capacidad distintiva de un producto. Las funciones se describen normalmente por lo que hacen dentro del producto. En general, los nombres de función van en minúscula, con excepciones.

Cuando escribas sobre una función, no la escribas con mayúscula salvo que el nombre esté oficialmente capitalizado. Si no estás seguro, sigue el precedente de otros documentos que describen la función. Como con los productos, copia la capitalización de la etiqueta de la interfaz si te refieres a una.

Recomendado El acuse de recibo de cis-admin responde al proveedor en menos de 8 horas.
La consola de emergencia de núcleo permite reiniciar el servidor.
No recomendado El Acuse de Recibo de cis-admin responde al proveedor en menos de 8 horas.
La Consola de Emergencia de núcleo permite reiniciar el servidor.

Nombres de servicio, repositorio y unidad

Los servicios y repositorios del grupo llevan el prefijo de la sociedad o marca que los opera, en minúscula y con guion: cis-admin, cis-auth, cis-mailer, cochid-datos, cochid-scribe, cds-protocolo. Cuando hablas del servicio como cosa, el nombre va en texto normal (cis-admin aprueba el asiento). Cuando te refieres al repositorio, a la unidad de systemd, al comando o al directorio, va en fuente de código (systemctl restart cis-admin). Nunca cambies el guion por espacio ni agregues mayúsculas: «Cis Admin» y «CIS-Admin» no existen.

Abreviar los nombres

Google pide usar siempre el nombre de producto completo y no abreviarlo, salvo para coincidir con una etiqueta de la interfaz. La casa va por otro camino en un punto y lo dice explícito: las tres sociedades tienen sigla oficial y la documentación la usa.

Recomendado La Compañía de Innovación de Santiago SpA (CIS) opera los servidores del grupo. CIS factura a sus dos relacionadas por ese servicio.
Firma el contrato en Firmas y Documentos.
No recomendado La CIS — la empresa operativa — opera los servidores del grupo (raya y sigla sin presentar).
Firma el contrato en Firmas.
Compañía Chilena de Inteligencia de Datos SpA y su sigla no coinciden: no escribas «CCID».

Piensa también si necesitas repetir el nombre del producto a lo largo del documento o si puedes usar un término más general. Por ejemplo, si ya dejaste claro que hablas del lago de datos de cochid-datos, puedes hablar de «el lago» o «la base» en buena parte del documento. Elige un término y mantenlo (P07).

Posesivos de los nombres de producto

El español forma el posesivo con «de», así que el problema del inglés (Cloud Datastore's) no existe. Lo que sí existe es la tentación de declinar el nombre: «el cis-admin», «los usaias», «la cochid». Para más información, consulta Posesivos.

Recomendado la API de cis-admin
los productos de la Compañía Chilena de Inteligencia de Datos
No recomendado la cis-admin API
los productos de la cochid

Artículos antes de los nombres de producto

En inglés la regla es no poner the antes de un nombre de producto, salvo que el nombre modifique otra cosa, y sí ponerlo antes de nombres de herramientas y API. El español pone más artículos que el inglés, así que la regla se adapta:

Recomendado Usar cochid-datos con cochid-scribe
La página de opciones de cis-admin
La consola de cis-mando
La API de cis-admin
La CLI vault
No recomendado Usar el cochid-datos con el cochid-scribe
Cis-admin página de opciones

Si usas un nombre de producto como modificador, revisa el género y el número del artículo: los decide el sustantivo, no el nombre.

Recomendado Un entorno de cochid-datos
Una instancia de cochid-datos
No recomendado Una entorno cochid-datos

Para más información sobre los artículos, consulta Artículos.

«Servicio» para referirse a varios productos

Google acepta llamar «servicios» a sus productos («el servicio Compute Engine»). En el grupo, «servicio» tiene además un significado fijo en el registro: «servicio interno» es una clase (admin, wiki, mando). Por eso, úsalo con cuidado. Está bien decir «los servicios de CIS» para el conjunto de lo que CIS opera. Si el término se confunde con la clase del registro o con systemd, usa los nombres de producto.

Recomendado CIS opera los servicios de sus dos relacionadas.
Los productos mapas y lex comparten la base de datos.
No recomendado Los servicios mapas y lex comparten la base de datos (mapas y lex son productos, no servicios internos).

No uses nombres de producto como verbos

No uses nombres de producto ni de función como verbos. La regla vale para los productos del grupo y para los de terceros (consulta Usa las marcas solo como modificadores en esta página).

Recomendado Publica la nota en Periodismo2.
Guarda el acta en el archivo societario.
Firma el documento en Firmas y Documentos.
No recomendado Periodismea la nota.
Archivéala.
Fírmala con Firmas.

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