Interfaces de computador

Esta sección fija cómo se escribe sobre lo que el lector ve en una pantalla o escribe en una terminal. Cubre comentarios de referencia de API, código dentro de una oración, muestras de código, comandos con sus argumentos, marcadores de posición y elementos de interfaz. Aplica a todo documento técnico del grupo: el manual de operación de vps-cis, los README de cis-admin y cochid-datos, los runbooks, la ayuda en pantalla y los procedimientos del archivo societario.

Seis temas, en este orden:

• Comentarios en referencia de API: qué describe cada docstring y con qué fórmula empieza.
• Código en el texto: qué va en tipografía de código y qué no.
• Muestras de código: sangría, largo de línea, omisiones y frase de entrada.
• Sintaxis de línea de comandos: prompt, argumentos opcionales, salida y terminología.
• Formato de marcadores de posición: <var>, mayúsculas con guion bajo y cómo explicarlos.
• Elementos de UI e interacción: negrita para lo que tiene nombre en pantalla, verbos, teclas.

Tres reglas de la casa atraviesan los seis temas y ganan sobre la fuente original: cero raya (P05: usa «·», paréntesis o punto y oración nueva), nunca voseo (P06) y títulos en minúscula de oración (P37). Donde el original usa Title Case, comillas inglesas o la raya para introducir un ejemplo, aquí verás la forma española.

Comentarios en referencia de API

Cuando documentas una API, entrega una referencia completa. Por lo general se genera desde el código fuente con comentarios de documentación (docstrings en Python, JSDoc o TSDoc en TypeScript) que describen todas las clases, métodos, constantes y demás miembros públicos.

Usa estas pautas según tenga sentido para el lenguaje. Esta sección no fija cómo se marca cada comentario: eso lo decide la herramienta que genera la referencia (Sphinx, pdoc, TypeDoc). El idioma del docstring sigue la convención del repo y no se mezcla dentro de un mismo módulo; la mayoría de los repos del grupo documentan en español.

Fuentes complementarias: AIP-192: Documentation (estándares de API de Google), Inline API documentation (guía de diseño de API de Google Cloud) y la guía de estilo de cada lenguaje.

Lo básico

La referencia de API debe traer una descripción para cada uno de estos elementos:

• Cada clase, interfaz, estructura y cualquier miembro equivalente de la API (por ejemplo, los tipos unión en C++ o los TypedDict en Python).
• Cada constante, campo, enumeración y alias de tipo.
• Cada método, con una descripción de cada parámetro, del valor de retorno y de las excepciones que lanza.

Lo que sigue son sugerencias muy fuertes. En algunos casos no calzan con una API o un lenguaje en particular, pero en general se cumplen:

• En cada página individual (de una clase, una interfaz, etc.), pon una muestra de código de 5 a 20 líneas al inicio.
• Pon todos los nombres de API, clases, métodos, constantes y parámetros en tipografía de código y enlaza cada nombre a su página de referencia. Casi todos los generadores lo hacen solos.
• Pon los literales de cadena en tipografía de código y enciérralos entre comillas dobles rectas. Por ejemplo, el estado de un asiento puede ser "borrador" o "aprobado".
• Escribe el nombre de una clase igual que en el código, con sus mayúsculas y sin espacios (por ejemplo, AsientoContable).
  • No pongas los nombres de clase en plural (Asientos, Movimientos); agrega un sustantivo en plural (objetos Asiento, instancias de Movimiento). Ver Plurales.
  • Si la clase tiene un nombre que además es un término común, puedes referirte a ella con la palabra en español, en minúscula y sin tipografía de código (el asiento, la conciliación).

Clases, interfaces y estructuras

En la primera oración de la descripción de una clase, di en breve su propósito o función con información que no se deduzca del nombre ni de la firma. En el resto de la documentación, explica cómo se usa la API: cómo se invoca o instancia, cuáles son sus funciones clave y qué buenas prácticas o trampas tiene.

Muchas herramientas extraen la primera oración de cada clase para armar la lista de todas las clases. Por eso la primera oración tiene que ser única, descriptiva y corta. Y también:

• No repitas el nombre de la clase en la primera oración.
• No digas «esta clase hace…» ni «esta clase hará…».
• No pongas un punto antes del final real de la oración: algunos generadores cortan la «descripción corta» en el primer punto que ven. Escribe «por ejemplo» en lugar de «p. ej.», y «número» en lugar de «N.º» dentro de esa primera oración.

El siguiente ejemplo es la primera oración de la descripción de la clase Conciliador de cis-admin:

Miembros

Haz las descripciones de los miembros (constantes y campos) lo más breves que puedas. Enlaza los métodos que usan esa constante o ese campo.

Por ejemplo, la descripción de la constante ESTADO_APROBADO de la clase Asiento:

Métodos

En la primera oración de la descripción de un método, di en breve qué acción ejecuta. En las oraciones siguientes, explica por qué y cómo usarlo, qué condiciones previas se cumplen antes de llamarlo, qué excepciones puede lanzar y qué APIs relacionadas existen.

Documenta toda dependencia necesaria para llamar al método (por ejemplo, pertenecer a un grupo de Authentik) y cómo se comporta si falta esa dependencia (por ejemplo, «el método lanza PermisoDenegado» o «el método devuelve None»).

Por ejemplo, la descripción del método Movimiento.esta_conciliado:

Usa el presente en todas las descripciones (ver Presente y Verbos en documentos de referencia):

Descripción

• Si el método ejecuta una operación y devuelve datos, empieza con el verbo de la operación:
  • Agrega un asiento al libro diario y devuelve el id de la entrada nueva.
• Si es un método de lectura (getter) que devuelve un booleano, empieza con «Comprueba si…».
• Si es un método de lectura que devuelve algo distinto de un booleano, empieza con «Obtiene el…» u «Obtiene la…».
• Si no devuelve nada, empieza con un verbo como estos:
  • Activar una capacidad o fijar un valor: «Establece el…».
  • Actualizar una propiedad: «Actualiza el…».
  • Borrar algo: «Elimina el…».
  • Registrar una función de retorno u otro elemento para uso posterior: «Registra…».
  • Para una función de retorno (callback): «Lo llama X cuando…» (por lo general en métodos cuyo nombre empieza con on_ o al_, como al_cerrar_periodo). Por ejemplo: «Lo llama el planificador cuando cierra el mes». Y más adelante en la descripción: «Las subclases implementan este método para…».
• Si es un método de conveniencia que construye el objeto de la clase, empieza con «Crea un…» o «Crea una…».

Parámetros

Para describir parámetros, sigue estas pautas:

• Empieza con mayúscula y termina la oración o frase con punto.
• Si puedes, empieza la descripción de un parámetro no booleano con «El», «La», «Un» o «Una»:
  • El id del asiento que quieres obtener.
  • Una descripción del movimiento.
• Para parámetros booleanos que le ordenan a la API hacer o no hacer algo, di qué hace la API si el parámetro es verdadero y qué hace si es falso. Por ejemplo:
  • validar_certificado: Si es verdadero, valida el certificado TLS antes de continuar. Si es falso, confía en el certificado sin validarlo.
• Para parámetros booleanos que declaran un estado ya establecido (en vez de ordenar algo), usa la fórmula «Verdadero si…; falso en caso contrario». Por ejemplo:
  • Verdadero si el período está cerrado; falso en caso contrario.
• En este contexto, las palabras «verdadero» y «falso» no van en tipografía de código ni entre comillas. Reserva true y false para el literal del lenguaje (ver Elementos que a veces van en código).
• Para parámetros con comportamiento por defecto, explica qué pasa con cada valor o rango de valores, y después di cuál es el valor por defecto con la fórmula Por defecto:.

Valores de retorno

Sé lo más breve que puedas en la descripción del valor de retorno; el detalle va en la descripción de la clase.

• Si el valor de retorno no es un booleano, empieza con «El…» o «La…»:
  • El asiento identificado por el id indicado.
• Si el valor de retorno es un booleano, usa la fórmula «Verdadero si…; falso en caso contrario»:
  • Verdadero si el asiento está aprobado; falso en caso contrario.

Excepciones

En lenguajes donde el generador de referencia inserta solo la palabra «Lanza» (o Raises, Throws), empieza la descripción con «Si…»:

• Si no hay clave asignada.

En los demás casos, empieza con «Se lanza cuando…»:

• Se lanza cuando no hay clave asignada.

Obsolescencia

Cuando algo queda obsoleto, dile al lector qué usar en su reemplazo. Si versionas la API, menciona en qué versión quedó obsoleto. El término de la casa es obsoleto; no uses el calco «deprecado» (ver Anglicismos y su forma en español).

Solo la primera oración de una descripción aparece en el resumen y en el índice, así que pon ahí la información más importante. Las oraciones siguientes pueden explicar por qué quedó obsoleto y cualquier otro dato útil para quien usa la API.

Si un método queda obsoleto, dile al lector qué hacer para que su código siga funcionando.

Código en el texto

En oraciones de texto corriente (a diferencia de las muestras de código), usa tipografía de código para marcar casi todo lo que tenga que ver con código. La tipografía de código le aclara al lector qué parte del texto nombra una entidad, de tres maneras:

• Le avisa que el texto se escribe tal cual, letra por letra.
• Le muestra dónde empieza y dónde termina lo que tiene que escribir.
• Separa con claridad la entidad del texto que la rodea.

Para marcar texto como código:

• En HTML, usa el elemento code.
• En Markdown, usa acentos graves (`).

Para elegir entre HTML y Markdown, ver Markdown contra HTML.

Esta sección explica cómo formatear código dentro de oraciones corrientes. Los casos vecinos están en Formato de marcadores de posición, Sintaxis de línea de comandos, Muestras de código y Títulos y encabezados.

Algunos elementos que van en tipografía de código

La tabla siguiente lista elementos que van en tipografía de código. No es exhaustiva.

cis-build: lock OK · avail=7449MB swap=5187MB
...
cis-build: terminó (rc=0)

Si un elemento con formato de código aparece en la interfaz, agrégale negrita. Ver Código en elementos de UI.

En general, no pongas comillas alrededor del código salvo que las comillas sean parte del código. Y al revés: nunca uses comillas para marcar código; las comillas no reemplazan la tipografía de código.

Elementos que van en tipografía normal

La tabla siguiente lista elementos que no van en tipografía de código. Tampoco es exhaustiva. Si te refieres a alguno de ellos como entrada o salida del computador, o como una entidad de código (un atributo, un valor), entonces sí va en código.

Casi siempre conviene formatear la URL como enlace con texto descriptivo en vez de exponer la URL. Ver Referencias cruzadas y enlaces.

Fíjate en la diferencia entre el producto y su unidad técnica. cis-admin (el producto) va en tipografía normal. cis-admin.service (la unidad systemd) y cis-admin (el nombre tal como aparece en un comando o en una lista de la interfaz) van en código.

Código en elementos de UI

Si un elemento de UI cumple los requisitos para ir en tipografía de código, usa código y negrita a la vez.

Elementos que a veces van en código

La lista siguiente incluye elementos que a veces van en tipografía de código. No es exhaustiva.

• Valores booleanos. Si te refieres directo a un valor del tipo booleano (como true o false, 1 o 0), formatea el valor como código. Si te refieres a la evaluación de una condición como verdadera o falsa, escríbelo en tipografía normal.
  Recomendado Si la actualización tiene éxito, devuelve true.
  validar_certificado: Si es verdadero, valida el certificado TLS antes de continuar. Si es falso, confía en el certificado sin validarlo.

  No recomendado Si la actualización tiene éxito, devuelve verdadero.
  validar_certificado: Si es true, valida el certificado TLS antes de continuar.
• Nombres de utilidades de línea de comandos. Es común que el nombre de una utilidad se escriba igual que el proyecto o producto al que pertenece, con la única diferencia de las mayúsculas. En esos casos, usa tipografía de código para el comando y tipografía normal para el nombre del proyecto o producto.
  Recomendado Invoca el compilador GCC 8.3 con gcc para programas en C o g++ para programas en C++.
  Para enviar el archivo por FTP con IPv6, usa ftp -6.
  Las opciones del comando curl están explicadas en el sitio del proyecto curl.
  El programa apt incluye comandos de los programas apt-get y apt-cache para trabajar con paquetes APT.
  El linter de prosa se invoca como prosa-lint; la norma vive en core/prosa.

  No recomendado Invoca el compilador GCC 8.3 con gcc para programas en C.
  Las opciones del comando curl están explicadas en el sitio del proyecto curl.
• Direcciones de correo como entrada o salida. Si quieres que el lector use la dirección como entrada o salida del computador, usa tipografía de código. Si quieres que la trate como una forma de contactar a alguien o como referencia a una persona, usa tipografía normal y enlázala.
  Recomendado Escribe el nombre de usuario, no el correo completo. Por ejemplo, escribe alex, no alex@example.com.
  Para pedir ayuda, escribe a soporte@example.com.

  No recomendado Para pedir ayuda, escribe a soporte@example.com.

Nombres de métodos

Cuando nombras un método en el texto, omite el nombre de la clase salvo que incluirlo evite una ambigüedad.

Códigos de estado HTTP

Para referirte a un solo código de estado, usa este formato y esta redacción:

un código de estado HTTP 400 Bad Request

En particular, llámalo código de estado, no código de respuesta ni código de error, y pon el número y el nombre en tipografía de código. El nombre del código no se traduce: es el texto que viaja en la respuesta. Si «HTTP» se entiende por el contexto, puedes omitirlo.

Para referirte a un rango de códigos, usa esta forma:

un código de estado HTTP 2xx o 400

Es decir, usa Nxx (con un dígito concreto en lugar de N) para decir cualquiera en el rango N00 a N99, y pon el número en tipografía de código aunque omitas el nombre.

Si prefieres indicar el rango exacto, puedes hacerlo:

un código de estado HTTP en el rango 200 a 299

Aquí también los números van en tipografía de código. Fíjate en que el rango se escribe con «a», no con guion ni raya (P05).

Tratamiento gramatical de los elementos de código

En general, no uses elementos de código (palabras clave, nombres de archivo) como si fueran verbos o sustantivos del español. No flexiones el nombre de un elemento de código: ni plural, ni género, ni terminación verbal. En su lugar, pon un sustantivo que diga qué es el elemento (la constante, el archivo, el método, la solicitud) y flexiona ese sustantivo.

Enlazar términos de API en la referencia generada

Cuando escribes comentarios de código que se convierten en referencia generada, enlaza la primera aparición de cada elemento de la API (clases, métodos, constantes, atributos) a su página de referencia. Usa tipografía de código y un elemento a corriente. En las apariciones siguientes dentro de la misma sección, mantén la tipografía de código pero no repitas el enlace.

Las clases muy comunes de un dominio no necesitan enlace cada vez. Si usas un término como concepto y no como clase, no lo pongas en tipografía de código ni con mayúscula inicial. Ejemplos de términos que en los repos del grupo se leen como concepto:

• asiento, asientos
• movimiento
• período
• cartola
• documento
• sesión

Si usas uno de estos términos para referirte a una instancia concreta, usa el nombre formal de la clase y enlaza su página de referencia.

Para enlazar una clase o un método:

• Para enlazar una clase, usa el nombre de la clase como texto del enlace: <a href="/ref/asiento">Asiento</a>.
• Para enlazar un método, usa el nombre del método como identificador de fragmento. Si el método es estático, incluye también el nombre de la clase en el texto del enlace. Si necesitas distinguir entre versiones sobrecargadas, muestra la firma completa: <a href="/ref/asiento#aprobar(int)">aprobar(int)</a>.

Muestras de código

Esta sección explica cómo formatear muestras de código. El código dentro de una oración, la sintaxis de comandos y los marcadores de posición tienen sus propias secciones: Código en el texto, Sintaxis de línea de comandos y Formato de marcadores de posición.

Pautas básicas

Sigue estas pautas al formatear muestras de código:

• Sigue la sangría de la guía de estilo del lenguaje y la configuración del repo. Para casi todos los lenguajes esto significa espacios en vez de tabuladores. La cantidad depende del lenguaje: 4 espacios en Python (PEP 8, black), 2 espacios en JavaScript, TypeScript, CSS, YAML y SQL, tabuladores en Go y en los Makefile. Si el repo tiene pyproject.toml, .prettierrc o .editorconfig, manda ese archivo. Esta pauta aplica a muestras de código, no a comandos.
• Corta las líneas a 80 caracteres. Si esperas que el lector tenga una ventana angosta o imprima el documento, considera un tope menor.
• Marca los bloques de código como texto preformateado. En HTML, usa un elemento pre; en Markdown, usa una cerca de código (```) con el nombre del lenguaje. La sangría de cuatro espacios también funciona en Markdown, pero en los repos del grupo se usa la cerca.
• Indica el código omitido con un comentario en la sintaxis del lenguaje de la muestra. No uses tres puntos ni el carácter de puntos suspensivos (…). Si un bloque tiene una omisión, no lo formatees como «copiar con un clic».

<pre>
function saludar() {
  alert('Hola. Esta oración es tan larga que se corta y sigue en una
    segunda línea.');
}
</pre>

function saludar() {
  alert('Hola. Esta oración es tan larga que se corta y sigue en una
    segunda línea.');
}

function saludar() {
    alert('Hola. Esta oración es tan larga que se corta y sigue en una segunda línea, y nadie la va a leer completa en una ventana angosta.');
}

[Unit]
Description=cis-admin backend
# Se omiten varias líneas.
[Service]
ExecStart=/srv/projects/releases/SHA/.venv/bin/uvicorn app.main:app --port 8244
Restart=always

[Unit]
Description=cis-admin backend
...
[Service]
ExecStart=/srv/projects/releases/SHA/.venv/bin/uvicorn app.main:app --port 8244
Restart=always

Frases de entrada

En casi todos los casos, antecede la muestra de código con una oración o un párrafo de entrada. La entrada puede terminar en dos puntos o en punto. Por lo general van dos puntos si la muestra viene justo después. Va punto si hay más material entre medio (como una nota) o si el párrafo de entrada termina con una oración que no se relaciona directo con la muestra. Ver Dos puntos.

Para ver cómo se introducen comandos, ver Sintaxis de línea de comandos.

Guías de estilo de código

Guías públicas que se usan como referencia en los repos del grupo:

• Python: PEP 8, con formato automático de black y ruff cuando el repo los declara.
• Shell: guía de shell de Google, en especial la sección de comillas.
• JavaScript y TypeScript: guía de JavaScript de Google; si el repo tiene Prettier, manda Prettier.
• HTML y CSS: guía de HTML/CSS de Google, más el canon de cis-style para tokens y tipografía.
• C++ y Java: guía de C++ y guía de Java de Google.
• Lista completa de guías de Google.

Algunos proyectos de código abierto tienen su propia guía y esa manda cuando contribuyes ahí. Por ejemplo, el código Java del Android Open Source Project sigue la guía AOSP Java Code Style for Contributors.

Sintaxis de línea de comandos

Esta sección muestra cómo documentar comandos de línea de comandos y sus argumentos. Los temas vecinos: Código en el texto, Formato de marcadores de posición y Muestras de código.

Buenas prácticas

Cuando escribes documentación procedimental o conceptual sobre un comando, aplica estas prácticas:

• Enlaza la referencia del comando. Un buen lugar para ese enlace es el texto que introduce el comando o la serie de pasos.
  Recomendado Para leer un secreto, usa el comando vault get:

  vault get cis-mailer RESEND_API_KEY_CIS

  No recomendado Ejecuta lo siguiente (la lista de opciones está en algún lado del manual):

  vault get cis-mailer RESEND_API_KEY_CIS

• Decide qué argumentos hacen falta para completar cada tarea de la manera recomendada. Para reducir la cantidad de opciones que documentas fuera de la referencia, usa la menor cantidad posible de argumentos opcionales. Deja la lista completa a la referencia del comando.
• Entrega un ejemplo para copiar con un clic que el lector no tenga que editar después de copiarlo. Si puedes, incluye solo código ejecutable y marcadores de posición en ese ejemplo.

  Algunos ejemplos contienen argumentos opcionales, argumentos mutuamente excluyentes o argumentos repetibles indicados con corchetes ([]), barras verticales (|), llaves ({}) y tres puntos (...). Esos caracteres rompen el comando si el lector no los quita. Por eso, evita esos argumentos en los ejemplos para copiar con un clic. Ver Argumentos opcionales en comandos para copiar.

Formato de un comando

Para marcar un bloque de código como un comando largo o una muestra, usa este formato:

• En HTML, usa el elemento pre.
• En Markdown, usa una cerca de código (```).

Para formatear un comando con varios elementos:

• Cuando una línea pasa de 80 caracteres, puedes cortarla sin riesgo antes de ciertos caracteres, como un guion simple, un guion doble, un guion bajo o unas comillas. Después de la primera línea, sangra cada línea con cuatro espacios para alinear en vertical todo lo que sigue a un corte.
• Cuando cortas una línea de comando, cada línea salvo la última tiene que terminar con el carácter de continuación. Un comando sin ese carácter no funciona.
  • Linux o macOS: una barra invertida precedida de un espacio ( \).
  • Windows: un acento circunflejo precedido de un espacio ( ^).
• Formatea los marcadores de posición según Formato de marcadores de posición.
• Después de la línea de comando, pon una lista descriptiva de los marcadores que usa. Ver Explicar los marcadores de posición.
• Cuando documentas una opción o un argumento, usa punto final en las oraciones completas. No uses punto final en palabras sueltas ni en frases nominales, salvo que mezcles oraciones y frases nominales en la misma lista. Es la misma pauta que en Listas.

Cuando documentas un comando de bash o sh, sigue la convención de comillas de la guía de shell de Google.

pg_dump -Fc --no-owner \
    --host=127.0.0.1 \
    --port=5432 \
    --username=cochid \
    --file=/srv/backups/cochid-datos/FECHA.dump \
    cochid_datos

pg_dump -Fc --no-owner --host=127.0.0.1 --port=5432 --username=cochid --file=/srv/backups/cochid-datos/FECHA.dump cochid_datos

Prompt de la terminal

Si tus instrucciones muestran varias líneas de entrada en un mismo bloque, empieza cada línea de entrada con el símbolo del prompt. Si no quieres que el lector copie el símbolo junto con el comando, puedes desactivar la selección de texto para ese símbolo, por ejemplo con CSS.

No muestres la ruta del directorio actual antes del prompt, ni siquiera si la instrucción incluye cambiar de directorio. Pero si cambia el contexto general de la interfaz (por ejemplo, de la máquina local a una remota), agrega un indicador de prompt distinto para el contexto nuevo.

$ systemctl --user list-units --type=service

UNIT                    LOAD   ACTIVE SUB     DESCRIPTION
cis-inbox.service       loaded active running cis-inbox
cis-mailer.service      loaded active running cis-mailer

illanes00@vps-cis:/srv/projects/cis$ systemctl --user list-units --type=service
UNIT                    LOAD   ACTIVE SUB     DESCRIPTION
cis-inbox.service       loaded active running cis-inbox

$ ssh vps-dev
vps-dev$ systemctl status core-claude
vps-dev$ exit
$ cis-note "core-claude activo en vps-dev"

$ ssh vps-dev
$ systemctl status core-claude
$ exit
$ cis-note "core-claude activo en vps-dev"

Cuando muestras un comando de una sola línea, el prompt (el símbolo $) es opcional. Pero si el documento mezcla comandos de una línea y de varias, usa el prompt en todos para mantener la consistencia.

Si las instrucciones combinan líneas de entrada y de salida, usa bloques separados para la entrada y para la salida.

$ cat ~/.ssh/id_ed25519.pub

ssh-ed25519 VALOR_DE_LA_CLAVE USUARIO

$ cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK... sopapo@mac

Argumentos opcionales

Usa corchetes alrededor de un argumento para indicar que es opcional. Si hay más de un argumento opcional, encierra cada uno en su propio par de corchetes.

Evita los argumentos opcionales en los ejemplos para copiar con un clic. Ver Argumentos opcionales en comandos para copiar.

En el siguiente ejemplo, PROYECTO y CLAVE son obligatorios, y el guion final (leer el valor desde la entrada estándar) es opcional:

vault set PROYECTO CLAVE [-]

Argumentos mutuamente excluyentes

Usa llaves para indicar que el lector tiene que elegir una (y solo una) de las opciones que van dentro. Puede haber más de dos opciones excluyentes. Para separar cada opción, usa una barra vertical (|).

Evita los argumentos mutuamente excluyentes en los ejemplos para copiar con un clic.

En el siguiente ejemplo, elige TEXTO o -:

cis-note {TEXTO|-}

En el siguiente ejemplo también hay dos opciones:

• Lado izquierdo de la barra: si el valor viene de un archivo, lo siguiente es obligatorio:
  set-file PROYECTO CLAVE RUTA
• Lado derecho de la barra: si el valor se escribe a mano:
  • set PROYECTO CLAVE es obligatorio.
  • - es opcional, como indican los corchetes.

vault {set-file PROYECTO CLAVE RUTA | set PROYECTO CLAVE [-]}

Argumentos que se pueden repetir

Usa tres puntos sin espacios (...) para indicar que el lector puede especificar varios valores para el argumento.

Evita los tres puntos en los ejemplos para copiar con un clic.

En este ejemplo, el lector puede pasar varias instancias del parámetro opcional ARGUMENTO:

cis-build COMANDO [ARGUMENTO ...]

Argumentos opcionales en comandos para copiar

Los argumentos opcionales, los mutuamente excluyentes y los repetibles contienen caracteres (corchetes, llaves, barras verticales, tres puntos) que rompen el comando si el lector no los quita. Evita esos tipos de argumento en los comandos para copiar con un clic. En su lugar, elige una de estas cuatro salidas:

• Quita los argumentos opcionales. Como buena práctica, usa solo los argumentos necesarios para completar la tarea en el caso más común. Si puedes, saca los argumentos opcionales del comando y enlaza siempre la referencia, donde el lector encuentra la lista completa.
  Recomendado Para revisar la prosa de un informe, usa el comando prosa-lint:

  prosa-lint informe.md

  Si quieres la salida en JSON para otra herramienta, usa el mismo comando con la opción --json.

  No recomendado Para revisar la prosa de un informe:

  prosa-lint [--modo {prosa|estricto}] [--json] ARCHIVO...

• Usa bloques separados para cada opción. A veces conviene entregar más de un bloque para copiar dentro de la misma sección.
  Recomendado Para revisar un informe, usa el comando prosa-lint:

  prosa-lint informe.md

  Si el documento es un runbook o un mensaje de error, agrega la opción --modo estricto:

  prosa-lint --modo estricto runbook.md

  No recomendado Para revisar un documento:

  prosa-lint [--modo estricto] ARCHIVO

  (el lector que copia y pega se lleva los corchetes)
• Documenta los argumentos opcionales en tareas separadas. A veces lo mejor es tratar cada opción en su propia sección.
  Recomendado Para revisar un documento en español, usa el comando prosa-lint.

  Revisar un informe

  Si el documento es un informe, un README o un mail, ejecuta este comando:

  prosa-lint informe.md

  Revisar un runbook

  Si el documento es un procedimiento, un runbook o copy de interfaz, incluye la opción --modo estricto:

  prosa-lint --modo estricto runbook.md

  No recomendado Para revisar un documento, ejecuta prosa-lint con o sin --modo estricto según el tipo de documento, que puede ser informe, README, mail, procedimiento, runbook o copy de interfaz.
• Avisa que el comando contiene argumentos opcionales. Si tienes que incluir los caracteres especiales, dilo cuando introduces el comando.
  Recomendado Para respaldar la base del lago de datos, usa el comando pg_dump con formato personalizado. En el siguiente ejemplo, la opción --schema es opcional y limita el respaldo a un esquema:

  pg_dump -Fc \
      --username=cochid \
      --file=RUTA_DEL_RESPALDO \
      [--schema=ESQUEMA] \
      cochid_datos

  Por ejemplo, el siguiente comando respalda solo el esquema gold en el archivo gold-2026-08-20.dump:

  pg_dump -Fc \
      --username=cochid \
      --file=/srv/backups/cochid-datos/gold-2026-08-20.dump \
      --schema=gold \
      cochid_datos

  No recomendado Ejecuta:

  pg_dump -Fc --username=cochid --file=RUTA_DEL_RESPALDO [--schema=ESQUEMA] cochid_datos

  (sin aviso, el lector copia los corchetes y el comando falla)

Salida de comandos

No tienes que mostrar la salida de cada comando. Agrégala solo si aporta: por ejemplo, si el lector necesita copiar un valor de la salida o verificar un valor en ella.

Si muestras la salida, usa una de estas frases de entrada para separar el comando de la salida:

Si quieres destacar algo de la salida, puedes personalizar la frase de entrada.

Para indicar que se omiten una o más líneas de la salida de ejemplo, usa tres puntos sin espacios (...) en una línea aparte. No uses el carácter de puntos suspensivos (…). Por ejemplo:

cis-build: lock OK · avail=7449MB swap=5187MB · dir=/srv/projects/cis/cis-www
vite v5.4.2 building for production...
...
cis-build: terminó (rc=0)

Más sobre cómo presentar la salida:

• El orden de los componentes dentro de un paso de procedimiento está en Procedimientos.
• Los marcadores de posición dentro de la salida están en Marcadores de posición en la salida.
• Los dominios y direcciones IP de ejemplo están en Dominios y nombres de ejemplo.

Terminología de línea de comandos

Cuando hablas de comandos y sus partes, tanto en las herramientas del grupo (vault, cis-build, cis-note, prosa-lint) como en comandos de Linux, sigue estas pautas:

• No fuerces la nomenclatura de una herramienta sobre la de otra. Lo que en la documentación de Google Cloud se llama flag es, en las herramientas del grupo y en Linux, una opción.
• Los comandos de Linux pueden ser complicados. Conviene describir qué hace el comando completo en vez de cómo se llama cada uno de sus elementos.
• Pregúntate si el lector necesita saber el nombre del elemento o si basta con explicar el comando.

En la prosa del grupo, el término genérico para cualquier elemento que no sea el comando es opción; argumento es el valor que recibe un comando o una opción (por ejemplo, un nombre de proyecto). Flag queda solo para citar la documentación de una herramienta que lo use así (ver Anglicismos y su forma en español).

Comandos del grupo

vault {projects | list PROYECTO | get PROYECTO CLAVE | set PROYECTO CLAVE [-] |
    set-file PROYECTO CLAVE RUTA | delete PROYECTO CLAVE}

La sintaxis de vault distingue entre el comando (vault) y el subcomando (get, set). En la documentación, sin embargo, «el comando vault get» es una forma aceptada de nombrar el conjunto.

Puedes usar un comando o subcomando solo o con una o más opciones. Un comando o una opción también puede recibir un argumento, por ejemplo el nombre de un proyecto.

Ejemplo de comando

vault projects

Ejemplo de comando con argumento

vault list cis-mailer

Ejemplo de comando con varios elementos

systemd-run --user --scope \
    --property=MemoryMax=2G \
    --unit=etl-dipres-$(date +%s) \
    -- \
    python -m datos.etl dipres \
    --desde=2024 \
    --hasta=2025 \
    --solo-catalogo

El comando anterior consta de estos elementos:

• systemd-run es el nombre del comando.
• --user y --scope son opciones sin valor.
• --property=MemoryMax=2G es una opción con un valor, que a su vez es una propiedad de systemd con su valor.
• $(date +%s) es una sustitución de comando que inserta la hora actual en segundos.
• -- solo separa las opciones de systemd-run del comando que va a ejecutar.
• python -m datos.etl dipres es el comando que corre dentro del ámbito; --desde, --hasta y --solo-catalogo son opciones de ese comando, no de systemd-run.

Comandos de Linux

Precaución: la sintaxis de los comandos de Linux es compleja. Esta sección cubre solo los elementos más comunes. Para una referencia detallada, ver The Linux Command Line.

Donde las herramientas del grupo usan los términos comodín opción y argumento, los comandos de Linux usan opciones, parámetros, argumentos y una serie de elementos de sintaxis especializados. Un ejemplo:

find /srv/projects/cis -follow -type f -name '*.caddy' | xargs grep -iHn reverse_proxy

El comando anterior consta de estos elementos:

• find es el nombre del comando.
• /srv/projects/cis es un argumento que indica la ruta donde buscar. Es más fácil llamarlo solo «ruta».
• -follow es una opción. El guion (-) es parte de la opción.
• -type es una opción con el valor f.
• -name es una opción con el valor '*.caddy', donde el asterisco (*) es un metacarácter que funciona como comodín. Los metacaracteres se usan en el shell de Linux para el globbing, la expansión de nombres de archivo. Además del asterisco, son metacaracteres el signo de interrogación (?) y el acento circunflejo (^).

Los resultados del primer comando se redirigen con una tubería (|) al comando xargs grep -iHn reverse_proxy. Otros símbolos de redirección son el signo mayor (>), el signo menor (<), el doble menor (<<) y el doble mayor (>>). Redirigir significa capturar la salida de un archivo, comando, programa, script o incluso de un bloque dentro de un script, y enviarla como entrada a otro archivo, comando, programa o script.

Señales de Linux

Las señales de Linux exigen un vocabulario que en el resto de la documentación se evita. Usa los términos de la tabla siguiente solo en el contexto del control de procesos. Los nombres de las señales no se traducen; los verbos sí, y cada señal tiene el suyo.

Formato de marcadores de posición

Esta sección explica cómo formatear marcadores de posición en comandos, muestras de código y cadenas de texto. No explica cómo implementar el estilo visual; sí muestra ejemplos de cómo esta guía los renderiza distintos del resto del texto. Los temas vecinos: Código en el texto, Sintaxis de línea de comandos y Muestras de código.

Los marcadores de posición en código y comandos de ejemplo representan valores que el lector tiene que reemplazar cuando usa la muestra. En la salida de ejemplo, representan valores que varían. En general, un marcador lleva un nombre descriptivo como valor por defecto.

Por ejemplo, el marcador ID_PROYECTO representa el id de un proyecto en código, comandos y salida de ejemplo.

En una salida de ejemplo, el marcador CODIGO_RESPUESTA_HTTP representa un código de respuesta HTTP; no se espera que el lector lo fije en un valor concreto.

Marcadores de posición

Cuando creas marcadores, sigue esta pauta general sobre la letra x:

• En general, no uses una x sola ni una serie de x como marcador; usa uno más informativo.
• En algunos contextos (como los códigos de estado HTTP), la serie de x es el estándar, así que ahí está bien usar, por ejemplo, xx.

Hay varias maneras de formatear marcadores según trabajes en HTML o Markdown, y según el marcador vaya dentro de una oración, en un bloque de código o en un párrafo. Los detalles, en las secciones siguientes.

Marcadores en texto corrido

Si los marcadores de tu muestra o comando aparecen dentro de una oración, usa este formato:

• En HTML, envuelve el marcador con el elemento var, así:

  <code><var>NOMBRE_DEL_MARCADOR</var></code>

• En Markdown, envuelve el marcador en acentos graves (`) y pon un asterisco (*) antes del primero y después del segundo (*`NOMBRE_DEL_MARCADOR`*).

Si el marcador no representa código ni un comando, usa este formato:

• En HTML, envuelve el marcador solo con el elemento var:

  <var>NOMBRE_DEL_MARCADOR</var>

Marcadores en bloques de código

Si los marcadores están en un bloque de código, usa este formato:

• En HTML, envuelve el bloque en un elemento pre y marca cada marcador con un elemento var:

  <pre>
  vault set-file <var>PROYECTO</var> <var>CLAVE</var> <var>RUTA</var>
  </pre>

• En Markdown, envuelve el bloque en una cerca de código (```). Dentro de una cerca no puedes aplicar negrita ni cursiva; el marcador queda en mayúsculas y se explica debajo.

  ```
  NOMBRE_DEL_MARCADOR
  ```

Texto del marcador

Usa mayúsculas con guion bajo como separador. El marcador es un identificador que vive dentro de código y de shells, así que va en ASCII: sin tildes y sin eñe. Escríbelo en español y, si una palabra lleva eñe, busca otra (EJERCICIO en vez de AÑO).

Si el contexto hace que las mayúsculas con guion bajo sean una mala idea (por ejemplo, un lenguaje donde eso colisiona con constantes reales), usa otra convención que tenga sentido, pero sé consistente dentro del documento.

No incluyas adjetivos posesivos en los marcadores.

Nota: puedes marcar la sintaxis de un comando con corchetes, llaves y tres puntos. No pongas esos corchetes, llaves ni puntos dentro del elemento var.

Explicar los marcadores de posición

Cuando usas un marcador en texto o en código, explícalo la primera vez que aparece. No hace falta repetir la explicación en el resto del documento, salvo que le sirva al lector, por ejemplo en estas circunstancias:

• El documento es largo.
• Has introducido varios marcadores más en un procedimiento largo.
• El documento no está pensado para leerse de principio a fin.

El siguiente es un ejemplo de comando que usa un marcador, con la explicación del marcador:

<pre>
journalctl -u <var>UNIDAD</var> -n 100 --no-pager
</pre>
<p>Reemplaza <code><var>UNIDAD</var></code> por el nombre de la unidad systemd
que quieres revisar.</p>

Un solo marcador

Para un solo marcador, usa esta fórmula:

• Reemplaza MARCADOR por una descripción de lo que representa.

Dos o más marcadores

Para dos o más marcadores, usa esta fórmula:

• Después de la línea de comando, pon una lista descriptiva de los marcadores que usa. Explica qué representa cada uno aunque a ti te parezca obvio.
• Introduce la lista con Reemplaza lo siguiente:
• Lista los marcadores en el orden en que aparecen en el comando.
• Marca cada marcador de una muestra o comando con los elementos code y var, seguidos de dos puntos y una descripción que empieza en minúscula. Si la muestra no es código, quita el elemento code. Por ejemplo:

  <li><code><var>UNIDAD</var></code>: descripción</li>

• Si la descripción incluye un ejemplo, introdúcelo con una coma y «por ejemplo», o con «como». La fuente original admite la raya aquí; en la casa no (P05):
  Recomendado

  <li><code><var>UNIDAD</var></code>: descripción, por ejemplo <code>cis-admin</code></li>

  <li><code><var>UNIDAD</var></code>: descripción, como <code>cis-admin</code></li>

  No recomendado

  <li><code><var>UNIDAD</var></code>: descripción&mdash;por ejemplo, <code>cis-admin</code></li>

• Cada elemento de la lista sigue el estilo de Listas.

Marcadores de posición en la salida

Si entregas una salida de ejemplo, explica los marcadores que aparecen en ella:

• Usa elementos var para identificar el texto del marcador en la salida.
• Después de la salida, pon una lista de los marcadores que usa.
• Introduce la lista con Esta salida incluye los siguientes valores:
• Lista los marcadores en el orden en que aparecen en el ejemplo.
• Marca cada marcador con un elemento var, seguido de dos puntos y una descripción que empieza en minúscula. Por ejemplo:

  <li><code><var>UNIDAD</var></code>: descripción</li>

• Si la descripción incluye un ejemplo, introdúcelo con una coma y «por ejemplo», o con «como». Nunca con raya (P05).

Más sobre salida en Salida de comandos.

{
  "servicio": "cis-admin",
  "release": "SHA_RELEASE",
  "db": "ok",
  "ultimo_asiento": NUMERO_ASIENTO,
  "saldo_actualizado_en": "FECHA_HORA",
  "url": "https://admin.innovacionsantiago.cl/api/status?release=SHA_RELEASE"
}

{
  "servicio": "cis-admin",
  "release": "xxxxxxx",
  "db": "ok",
  "ultimo_asiento": 604,
  "saldo_actualizado_en": "2026-08-20T09:15:00-04:00"
}

Elementos de UI e interacción

Céntrate en la tarea

Cuando sea práctico, escribe las instrucciones en términos de lo que el lector tiene que lograr, no de los controles y gestos. Al no nombrar los elementos de la interfaz, ayudas al lector a entender el propósito de la instrucción y el procedimiento resiste mejor los cambios de diseño.

Pero conoce a tu audiencia y el contexto. En algunos casos, el objetivo del procedimiento es guiar al lector por los elementos de la página. O la interfaz no es obvia y conviene explicar los gestos para completar un paso. Entrega el nivel de detalle que le sirva a la audiencia prevista.

El resto de esta sección cubre los casos en que decidiste que conviene hablar de los elementos de la interfaz. Para escribir procedimientos, ver Procedimientos.

Formato de los nombres de elementos de UI

Cuando nombras cualquier elemento de la interfaz, pon su nombre en negrita con el elemento b en HTML o ** en Markdown. Esto incluye botones, menús, diálogos, ventanas, elementos de lista y cualquier otra cosa de la página que tenga un nombre visible. No uses tipografía de código para elementos de UI, salvo que el elemento cumpla los requisitos para ir en código. En ese caso, usa código y negrita a la vez.

Nota: se usa el elemento b porque en HTML moderno b connota texto al que quieres atraer la vista, mientras que el elemento strong indica importancia fuerte.

No pongas en negrita el nombre oficial de una función o de un producto, salvo cuando se refiere directo a un elemento de la página que usa ese nombre (como el título de una ventana o el texto de un botón).

Si documentas un elemento de UI fuera de un procedimiento, dale contexto al elemento.

Usa las mayúsculas que corresponden

En casi todos los casos, sigue las mayúsculas tal como aparecen en la página. Pero si las etiquetas son inconsistentes o están todas en mayúscula, usa minúscula de oración. En español no existe el Title Case (P37): si la interfaz dice Nuevo Asiento por un descuido del desarrollador, en la documentación va Nuevo asiento y se abre un ticket para corregir la interfaz.

Nombrar elementos de UI

No uses los elementos de UI como si fueran verbos o sustantivos del español.

Terminología y uso

Una interfaz puede contener muchos tipos de elementos. En general, céntrate en la función, no en el elemento. Si crees que le aclara algo al lector, usa el nombre del elemento. Por ejemplo, estas dos oraciones son válidas:

No uses jerga para los elementos de UI, como hamburguesa o zippy. Ver Botones e iconos.

Las secciones siguientes definen los términos para nombrar elementos de UI. Para las preposiciones que van con cada uno, ver la tabla de Preposiciones.

Ventanas, páginas, diálogos, paneles y secciones

Casi siempre, una ventana es la ventana completa de la aplicación en un entorno de escritorio. Pero también puede referirse a elementos modulares de la aplicación que se abren y cierran. Por ejemplo, en un IDE hay varias ventanas disponibles en el menú Ver > Ventanas de herramientas.

Página es el término preferido para una página web en general y para una subpágina de una consola en particular.

Un diálogo es una ventana más pequeña, por lo general separada de la ventana principal, que aparece delante de ella. La casa usa diálogo; no pop-up, ventana emergente ni modal en prosa (ver Términos de la casa).

Un panel es una región rectangular distinguible dentro de una ventana mayor del navegador o de la aplicación. Un panel suele estar acoplado a las regiones vecinas, mientras que una ventana está separada y se puede ocultar. No uses ventana, sección, área ni columna para referirte a un panel.

Una sección es un grupo con etiqueta de opciones y controles, por lo general dentro de una ventana o de un panel. No uses área ni columna para referirte a una sección.

Menús y barras de menús

En una aplicación de escritorio, la barra de menús aparece en la parte superior de la ventana o de la pantalla. Es un conjunto de menús (como Archivo o Editar), cada uno de los cuales es un conjunto de comandos relacionados o de submenús anidados.

Para referirte a un elemento de un menú, usa el término comando, no opción, elemento de menú ni alternativa. Excepción: si documentas cómo construir una interfaz, puedes usar elemento de menú.

Para referirte a un menú, usa la forma el menú NOMBRE.

Para decirle al lector dónde encontrar un comando dentro de un menú o submenú, usa una frase como En el menú Archivo, selecciona Abrir.

No uses desplegable como sinónimo de menú.

Usar el signo mayor

Otra opción es usar el signo mayor (>) para encadenar menús. Si lo usas, sigue estas pautas:

• Pon un espacio duro ( ) antes de cada signo mayor.
• No pongas en negrita cada menú por separado; encierra toda la secuencia en un solo par de etiquetas (<b>...</b> o **...**).
• Envuelve el signo mayor en un span con un atributo aria-label que diga y luego (por ejemplo, <span aria-label="y luego">></span>). Si no, algunos lectores de pantalla leen > como «mayor que».

En el siguiente ejemplo, el texto se renderiza como Selecciona Ver > Herramientas > Herramientas para desarrolladores. Un lector de pantalla lo interpreta como Selecciona Ver y luego Herramientas y luego Herramientas para desarrolladores.

HTML

Selecciona <b>Ver&nbsp;<span aria-label="y luego">></span> Herramientas&nbsp;<span aria-label="y luego">></span> Herramientas para desarrolladores</b>.

Markdown

Selecciona **Ver&nbsp;<span aria-label="y luego">></span> Herramientas&nbsp;<span aria-label="y luego">></span> Herramientas para desarrolladores**.

Esta notación sirve para abreviar una frase larga como En el menú Archivo, selecciona Abrir. Pero aplica solo a elementos de menú. No la uses para describir una combinación de elementos de UI distintos.

Menú de navegación

Un menú de navegación es un control (por lo general un panel o una ventana) que contiene una lista de elementos en los que el usuario hace clic para ir a páginas de una aplicación o sitio. No uses barra de navegación, panel de navegación ni ventana de navegación para ese control.

Barra de herramientas

Una barra de herramientas es un conjunto de botones para acciones frecuentes. Un botón de la barra que incluye un menú se llama botón de menú. Nombra la barra si crees que el usuario necesita ayuda para encontrar un botón.

Botones e iconos

Un botón inicia una acción cuando se hace clic en él (o se toca, en una pantalla táctil). Para referirte a un botón, usa su etiqueta.

Un icono es un símbolo o imagen que representa un objeto o una función. Un icono también puede ser un botón. Si el botón incluye un icono, escribe el nombre del botón tal como aparece en la descripción emergente (tooltip) y pon el icono antes del nombre. Si necesitas un espacio entre el icono y el nombre para que se lea bien, usa un espacio duro.

Si la descripción emergente del icono es idéntica al nombre del icono, usa un atributo alt vacío.

Si no sabes el nombre del icono, inspecciona el elemento con las herramientas del navegador. En muchos casos, un elemento visual como un icono tiene un atributo ARIA con una descripción textual para lectores de pantalla. Para inspeccionar un elemento, haz clic derecho sobre él y selecciona Inspeccionar o Inspeccionar elemento, según el navegador. Busca una de estas etiquetas: aria-labelledby, aria-label, aria-describedby, label, placeholder o title. Más información en Using aria-label y Accessible Name and Description calculation.

Si un botón con icono no tiene descripción emergente, abre un ticket para que la agreguen. Las descripciones emergentes son esenciales para la accesibilidad, para la documentación y para que el lector encuentre las cosas.

Si el nombre de un elemento de UI termina en puntos suspensivos (...), omítelos.

No uses lenguaje direccional para orientar al lector, como arriba, abajo o a la derecha. Esas frases funcionan mal para la accesibilidad y para la localización. Si un elemento es difícil de encontrar, agrega una captura de pantalla.

Elementos difíciles de encontrar

Si un elemento de UI es difícil de encontrar, considera una de estas alternativas al lenguaje direccional:

• Usa el icono del botón junto con su nombre tal como aparece en la descripción emergente.
  Recomendado Haz clic en ↻ Actualizar.

  No recomendado Haz clic en el botón de arriba a la derecha.
• Agrega contexto para ayudar al usuario a encontrar el elemento.
  Recomendado En la barra de herramientas de cis-mando, haz clic en ↻ Actualizar.

  No recomendado Haz clic en Actualizar, el que está al lado del otro botón.
• Usa una captura de pantalla.
  Recomendado En la lista de servicios, haz clic en ▥ Opciones de columnas.
  [captura: lista de servicios con el botón destacado]
  Para saber cuándo y cómo usar capturas, ver Figuras e imágenes.

  No recomendado En la lista de servicios, más o menos a la mitad de la pantalla, haz clic en el iconito de columnas.

Pestaña

Una pestaña es un elemento de navegación con forma de pestaña de carpeta. Para referirte a una pestaña, usa la forma la pestaña NOMBRE.

Campo de texto

Un campo de texto es una caja donde el usuario escribe. La casa usa campo y la forma el campo NOMBRE; no uses cuadro de texto ni caja. Formatea el texto que el usuario escribe con el elemento code en HTML, o con formato de código (monoespaciado) en otros lenguajes de marcado.

Lista, cuadro combinado y selector numérico

Una lista (o cuadro de lista) es un control que le ofrece al usuario una lista de elementos. Para referirte a ella, usa la forma la lista NOMBRE.

Un cuadro combinado es una combinación de campo de texto y lista. Para referirte a él, usa la forma el campo NOMBRE. Para describir cómo se ingresa un valor, usa los verbos escribe o selecciona, o ingresa.

Un selector numérico es un campo que le permite al usuario elegir un valor con flechas o escribiéndolo. Para referirte a él, usa la forma el campo NOMBRE. Para describir cómo se ingresa un valor, usa el verbo ingresa.

Casilla

Una casilla es un cuadro pequeño que indica si una opción está activada o no. Para referirte a ella, usa la forma la casilla NOMBRE.

En inglés los verbos check y uncheck son ambiguos; en español, marca y desmarca no lo son y son la forma de la casa. No uses chequea, tilda ni destilda.

Si necesitas referirte al estado de la casilla, di marcada o desmarcada.

Botón de opción

Un botón de opción (o botón de radio) es un botón pequeño que sirve para elegir un elemento de un grupo de opciones mutuamente excluyentes. Para referirte a él, usa su etiqueta, o refiérete al grupo por la etiqueta del grupo.

Flecha de expansión

Una flecha de expansión es el elemento de UI que expande o contrae una sección de navegación o de contenido. Evita nombrarla en la documentación; cuando lo hagas, usa flecha de expansión y sección expandible, no expando ni zippy.

Interruptor

Un interruptor (toggle) es el elemento de UI que alterna entre los estados activado y desactivado. No uses togglear ni alternar como verbo. Describe la acción que quieres que el usuario haga.

A veces no sabes en qué estado está el interruptor antes de que el usuario lo toque; en ese caso, di con claridad en qué posición tiene que quedar.

Presionar y escribir teclas

Para indicar que el usuario tiene que presionar una tecla o una combinación, usa el elemento kbd.

Un ejemplo de etiqueta <kbd>:

Si trabajas con un lenguaje de marcado que no es HTML, usa formato monoespaciado, que es como se renderiza el elemento kbd.

Para referirte a una tecla de letra, usa mayúscula, no minúscula.

Para referirte a una tecla que el usuario escribe para ingresar su valor como texto, usa el elemento code, no kbd. Ver Resumen de formato de texto.

Para referirte a una tecla, usa su nombre. Si es ambiguo, usa la forma la tecla NOMBRE.

Escribe completos los nombres de las teclas modificadoras: Control, Mayús, Alt, Comando, Opción. No uses símbolos (⌘, ⇧) ni las abreviaturas Ctrl y Shift. Para una combinación, usa la forma MODIFICADORA+TECLA.

Cuando entregas atajos para varios sistemas operativos, pon el atajo de macOS entre paréntesis después del de Windows y Linux.

Para una tecla o combinación que usa la tecla Mayús, usa la forma MODIFICADORA+Mayús+TECLA.

Escribe con palabras los nombres de los caracteres que pueden confundir dentro de un atajo, como coma, guion, punto y más.

Para referirte a un atajo, usa atajo de teclado o combinación de teclas.

Para describir la acción de presionar una tecla o combinación que provoca algo, usa el verbo presionar. Para describir la acción de escribir una tecla o combinación como parte de un texto, usa los verbos escribir o ingresar.

Preposiciones

La guía original distingue entre in y on según el elemento. En español las dos se traducen por en, así que la regla se reduce a una: usa en para todos los elementos de UI. Lo que sí importa es no reemplazarla por sobre, dentro de ni a través de.

Verbos en procedimientos

Para describir una acción en la página, usa estos verbos. Todos van en imperativo de tú (P06: nunca voseo). En los documentos en modo estricto de la norma de prosa (runbooks, mensajes de error), la orden va en infinitivo según P29: «Hacer clic en Guardar». Cada verbo tiene su entrada en la lista de palabras.

Para escribir procedimientos, ver Procedimientos.

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