Formato y organización

Esta sección fija cómo se presentan en la página las piezas que no son prosa corrida: fechas, números, unidades, listas, tablas, figuras, avisos, procedimientos y encabezados. Cada tema traduce y adapta la página correspondiente de la guía de Google. Donde el español o la casa piden otra cosa (coma decimal, hora de 24 h, títulos en minúscula de oración, cero rayas), la regla local se dice explícita y gana. Los ejemplos usan los sistemas del grupo: cis-admin, cochid-datos, el manual de operación de vps-cis y el archivo societario.

Fechas y horas

Una fecha o una hora ambigua le cuesta al lector una verificación. Escríbelas de modo que no admitan dos lecturas.

Horas

• Usa el reloj de 24 horas en todo el grupo: 14:30, 09:05. Google prefiere el de 12 horas con AM y PM; la casa no lo usa porque la UI, los logs de systemd, Caddy y Postgres ya están en 24 h y mezclar dos relojes en una misma página confunde.
• Separa horas y minutos con dos puntos. Escribe siempre los minutos; para las horas en punto, 15:00 (no 15 h en tablas ni en UI; en prosa corrida «a las 15 horas» es aceptable).
• Prefiere la hora exacta. «Mediodía» y «medianoche» son aceptables cuando el dato es aproximado.
• En un rango de horas usa «de … a …»; en tablas y encabezados, guion sin espacios.

Zonas horarias

Evita la zona horaria salvo que sea imprescindible, por ejemplo al documentar un hecho real ocurrido a una hora real (el freeze del 2026-08-05, una ventana de mantención). Si la necesitas:

• Indica si la hora es local para el lector: «10:00 hora local».
• Usa el formato de marca de tiempo que muestra la interfaz, si existe (los logs de vps-cis marcan en -04).
• Escribe el nombre completo de la región y la diferencia con UTC entre paréntesis. No abrevies el nombre de la zona (CLT, CLST, PST) porque esas siglas no se traducen ni se buscan bien.
• Si el hecho no cambia con el horario de verano, usa la zona fija sin referencia a UTC.

Fechas

En prosa, escribe el mes con su nombre y el año con cuatro cifras. En español el mes y el día de la semana van en minúscula y la fecha lleva «de» entre sus partes. No se pone coma después del año (la coma que pide Google es una convención del inglés).

Si incluyes el día de la semana, va antes del día del mes, sin coma: «martes 27 de abril de 2026».

Fechas parciales y abreviaturas

• Mes y año solos: «en enero de 2026». Sin coma ni en medio ni después.
• No abrevies el mes ni el día de la semana en prosa. En tablas y encabezados, donde el espacio manda, abrevia con las formas del español, con punto: lun., mar., mié., jue., vie., sáb., dom.; ene., feb., mar., abr., may., jun., jul., ago., sept., oct., nov., dic.
• Si abrevias, abrevia la fecha entera. No mezcles formas completas y abreviadas en una misma fecha.
• Sé consistente en todo el documento: si abrevias en una celda, abrevia en todas.

Por qué preferimos la fecha en letras

No expreses el mes como número cuando tienes alternativa. Una misma fecha numérica se lee distinto según la región:

• En Chile y el Reino Unido, 04/05/09 es el 4 de mayo de 2009 (día, mes, año).
• En Estados Unidos, 04/05/09 es el 5 de abril de 2009 (mes, día, año).
• En otras regiones, 04/05/09 es el 9 de mayo de 2004 (año, mes, día).

Formato numérico

La casa admite dos formatos numéricos, cada uno en su lugar:

• 20-08-2026 (día-mes-año, con guiones y año de cuatro cifras). Va en tablas, encabezados, formularios y cualquier superficie que lea una persona en Chile.
• 2026-08-20 (ISO 8601, año-mes-día). Va en nombres de archivo, logs, claves, columnas que se ordenan y todo lo que lea una máquina. Es el formato de .bak-<ts>, de los planes en cis/docs/plans/ y de las migraciones.

Nunca uses barras ni el año de dos cifras. Si eliges la fecha de un ejemplo ficticio, elige un día mayor que 12 para que no se confunda con el mes.

Fecha y hora juntas

Si debes dar fecha y hora, primero la fecha y después la hora, unidas por «a las». En formato máquina, ISO 8601 completo.

Divisiones del año

No uses estaciones. La primavera del hemisferio norte es otoño en Chile, y buena parte de lo que el grupo lee y cita (DIPRES, BID, proveedores) viene del norte. Usa el mes, el trimestre o la temperatura, según lo que importe.

Ejemplos

No uses dominios, correos, teléfonos, RUT ni nombres reales en los ejemplos. No reveles información personal (dominios, correos, teléfonos, nombres, nombres de proyecto, números de tarjeta). Usa datos ficticios de las listas de este tema o marcadores de posición como USER_ID o EMAIL_ADDRESS. La nomenclatura de dominios y nombres de ejemplo se amplía en Dominios y nombres de ejemplo.

Dominios de ejemplo

Cuando necesites un dominio genérico usa example.com, example.org o example.net. La IANA los reserva para documentación. El grupo no posee dominios reservados para ejemplos; no uses dominios del grupo (innovacionsantiago.cl, cochid.cl) como relleno ficticio, porque resuelven a servicios reales. Si el ejemplo trata de ese servicio, el dominio real es el correcto.

Si necesitas un nombre de dominio internacionalizado, usa uno de los TLD de prueba de IDN y copia la columna «URL del sitio de prueba».

Correos de ejemplo

Combina uno de los dominios de ejemplo con uno de los nombres de persona de este tema: dana@example.com. Las direcciones genéricas como soporte@example.net están bien. No uses nombres de personas reales, de productos ni inventados en la dirección.

Nombres de persona de ejemplo

Cuando necesites un nombre de pila, tómalo de esta lista. Funcionan en español y no cargan un género evidente:

• Alex
• Amal
• Ariel
• Bola
• Charlie
• Cruz
• Dana
• Dani
• Hao
• Ira
• Izumi
• Jie
• Kai
• Kalani
• Kim
• Kiran
• Lee
• Lucian
• Luka
• Mahan
• Noam
• Nur
• Quinn
• Raha
• Rosario
• Sasha
• Tal
• Taylor
• Tristan
• Yuri

Apellidos de ejemplo

Cuando necesites un apellido, usa una inicial después del nombre: Quinn N. o Dana A.

RUT de ejemplo

Chile no reserva un rango de RUT para ficción. Usa el marcador RUT o, si el ejemplo necesita un RUT con forma real, 12.345.678-K: su dígito verificador es inválido a propósito (el correcto sería 5), así que no puede pertenecer a nadie. Los RUT de las sociedades del grupo (CIS 78.384.591-1, CDS 78.372.913-K, COCHID 78.374.391-4) son públicos y se usan cuando el documento trata de esas sociedades, nunca como relleno.

Notas sobre las personas de ejemplo

Cuando escribes sobre personas, aunque sean hipotéticas, te leen personas reales que deben sentirse respetadas y bienvenidas. Tu audiencia incluye distintos oficios, contextos culturales y orígenes; incluye esa variedad en los ejemplos.

El español no tiene un pronombre neutro asentado como el they del inglés. Evita especificar el género salvo que sea esencial para la información: reformula con el nombre, con «la persona» o con el rol («quien aprueba el asiento»). Evita ejemplos que dependan de un binario de género. Si un ejemplo exige género, revisa que el nombre elegido no lleve una connotación contraria en la lengua o cultura de destino.

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

• Roles y niveles, como «gerente», asignados siempre a una persona de un mismo género.
• Roles, como «desarrollador» o «ingeniera», asignados siempre a un mismo origen étnico.

Usa los nombres de la lista anterior en casi toda la documentación. Parte de la documentación de seguridad usa el elenco de Alice y Bob. No uses a Alice y Bob salvo que documentes una especificación técnica que los usa; si los usas, usa solo nombres de ese elenco. Más guía en Lenguaje inclusivo.

Nombres de empresa de ejemplo

Cuando necesites una empresa, usa «Organización Ejemplo». Si necesitas distinguir dos empresas ficticias, agrega una descripción: «Organización Ejemplo Corporativa» y «Organización Ejemplo Emergente». Cuando el ejemplo pide una sociedad chilena con forma jurídica, «Organización Ejemplo SpA».

Teléfonos de ejemplo

La mayoría de los teléfonos de la documentación son ejemplos. Chile no reserva un rango para ficción; el único rango reservado conocido es el estadounidense 800-555-0100 a 800-555-0199. Usa el marcador TELEFONO o, si necesitas un número con forma real, uno de ese rango escrito en formato internacional y dilo. Nunca uses un número real. El formato se detalla en Teléfonos.

Direcciones IP de ejemplo

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

• 192.0.2.0 a 192.0.2.255
• 198.51.100.0 a 198.51.100.255
• 203.0.113.0 a 203.0.113.255

Para rangos IPv4 usa estos ejemplos:

• 192.0.2.0/24
• 198.51.100.0/24
• 203.0.113.0/24

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

• 2001:db8::
• 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
• 2001:db8:1:1:1:1:1:1
• 2001:db8:2:2:2:2:2:2
• 2001:db8:3:3:3:3:3:3
• 2001:db8:4:4:4:4:4:4

Para rangos IPv6 usa 2001:db8::/32.

Direcciones postales de ejemplo

No uses direcciones reales. Usa una de estas direcciones ficticias:

• Avenida Ficticia 1903, depto. 45
  Providencia, Región Metropolitana
• Avenida da Pastelaria, 1903
  Lisboa, 1229-076
• 8 Rue du Nom Fictif
  341 Paris

Los domicilios legales de las sociedades del grupo se usan solo en documentos que tratan de esas sociedades (actas, cartas del archivo), no como relleno.

Nombres de proyecto de ejemplo

Cuando necesites un nombre de proyecto, crea uno descriptivo y aplicable al entorno del lector. No uses componentes opacos como foo, bar y baz. Cuando haga falta, usa un sufijo numerado.

Identificadores de cuenta de servicio de ejemplo

Cuando necesites un identificador único de cuenta de servicio en un ejemplo, usa el identificador numérico 123456789012345678901.

Figuras e imágenes

Usa imágenes solo cuando explican algo que las palabras expresan mal. Con las capturas de pantalla, sé discreto: captura solo la parte de la interfaz que importa para la discusión.

Crear y guardar imágenes

• Para un diagrama, usa cualquier herramienta de dibujo.
• Para una captura, usa cualquier herramienta de captura.
• No uses imágenes de texto, de muestras de código ni de salida de terminal. Usa texto real: se busca, se copia y lo lee el lector de pantalla.
• Para diagramas (arquitectura, flujos, a diferencia de las capturas):
  • Usa SVG si puedes: no pierde nitidez al ampliar.
  • Si no tienes SVG, guarda en PNG salvo que tengas una buena razón para otro formato.
  • Sea cual sea el formato, no uses fondo transparente: falla con el tema oscuro del kit y con los visores de ampliación.
• Para animaciones y video, no uses GIF animado. Usa un formato más liviano, como MP4.
• Sé consistente en el sistema operativo de las capturas dentro de un documento o conjunto: todas en Linux o todas en macOS. Sé consistente también en la apariencia: si una captura incluye la sombra de la ventana, que las similares también.
• Recorta la captura a la información relevante. No incluyas la ventana entera si quieres mostrar un botón o un ítem de menú. El recorte enfoca al lector y protege la captura de cambios en otras partes de la interfaz.
• No incluyas información personal en las capturas. Si la captura original la tiene (un RUT, un saldo bancario en cis-admin, un correo en cis-inbox), tápala con un bloque de color sólido al 100% de opacidad. No confíes en desenfoques ni mosaicos: se revierten. Si exportas a un formato con capas (PDF, TIFF), aplana la imagen al exportar.
• No uses mapas de imagen. Da una lista de referencias en texto después de la imagen. Razones:
  • Son un problema de accesibilidad.
  • La implementación varía entre navegadores y suelen fallar en móvil por el escalado.
  • Mantener una capa de coordenadas cuesta más de lo que rinde.
• Usa nombres de archivo descriptivos. Ver Nombres de archivo.

Texto asociado a las imágenes

El texto alternativo, la leyenda y la descripción de la figura cumplen funciones distintas. Además de ellos, casi toda imagen va precedida por una oración introductoria. La oración termina en dos puntos si la imagen la sigue de inmediato y en punto si hay material entre medio (una nota, por ejemplo). Introduce siempre la imagen con una oración completa. No necesitas introducir una captura que sigue a un paso de procedimiento que describe esa misma interfaz.

Ejemplo

El siguiente diagrama muestra cómo se reparten los dominios del lago de datos de cochid entre esquemas:

Figura 1. Las fuentes se separan en dominios que migran a esquemas bronze, silver y gold.

En la figura 1, las fuentes del lago se separan en dominios y migran a esquemas de la siguiente forma:

• Las capacidades de ingesta y catálogo se agrupan en estas categorías:
  • La ingesta cruda migra al esquema bronze.
  • La limpieza y deduplicación migra al esquema silver.
  • Las vistas materializadas de consumo migran al esquema gold.
• Las capacidades de publicación se agrupan en una sola categoría:
  • El mirror y la API pública se unen y migran a datos.cochid.cl.

En HTML:

<p>El siguiente diagrama muestra cómo se reparten los dominios del lago de datos de cochid entre esquemas:</p>
<figure id="dominios">
  <img src="/img/cochid-datos-dominios.svg"
       alt="Los dominios del lago se reparten en tres esquemas.">
  <figcaption><b>Figura 1.</b> Las fuentes se separan en dominios que migran
  a esquemas bronze, silver y gold.</figcaption>
</figure>
<div id="descr-1">
  <p>En la figura 1, las fuentes del lago se separan en dominios y migran a
  esquemas de la siguiente forma:</p>
  <ul>…</ul>
</div>

En Markdown:

El siguiente diagrama muestra cómo se reparten los dominios del lago de datos de cochid entre esquemas:

![Los dominios del lago se reparten en tres esquemas.](/img/cochid-datos-dominios.svg)

**Figura 1.** Las fuentes se separan en dominios que migran a esquemas bronze, silver y gold.

En la figura 1, las fuentes del lago se separan en dominios y migran a esquemas de la siguiente forma:

- …

Texto alternativo

El texto alternativo es una descripción concisa que reemplaza a la imagen cuando no se ve: lectores de pantalla, navegadores de solo texto, conexiones lentas. Considera el contexto de la imagen, no solo su contenido. El atributo alt ayuda a la navegación con lector de pantalla, a la validación del marcado y al posicionamiento en buscadores.

Si la imagen es decorativa (no informativa) o solo apoya visualmente algo que el texto ya dice, usa texto alternativo vacío (alt="") para que la tecnología de asistencia la ignore. Son decorativas, por ejemplo:

• Una captura de la interfaz que muestra cómo llenar campos ya descritos en el texto.
• Los íconos de la interfaz.
• Las imágenes cuyo único fin es hacer la página más vistosa.

En el elemento img el atributo alt es obligatorio, aunque su valor sea una cadena vacía. Si lo omites, el lector de pantalla puede leer el nombre del archivo en voz alta. La especificación de HTML lo resume así: reemplazar cada imagen por su texto alternativo no debe cambiar el sentido de la página. Si el texto alternativo repite lo que ya dice el texto vecino o no le sirve a quien no ve, usa la etiqueta vacía.

Al escribir texto alternativo:

• No incluyas frases como «Imagen de» o «Foto de».
• Incluye puntuación: el lector de pantalla hace pausa en ella.
• Usa el mismo texto alternativo para cada repetición de una misma imagen (controles, indicadores de estado, íconos).
• Evita las mayúsculas sostenidas: algunos lectores deletrean.
• Introduce el diagrama en el texto, no en el texto alternativo.
• No uses la leyenda para reemplazar el texto alternativo.
• Usa oraciones completas o un sintagma nominal.
• Escríbelo corto y descriptivo: 155 caracteres o menos.
• Si la imagen contiene más información de la que cabe en 155 caracteres, pon un resumen breve en alt y una descripción extensa en el texto.

Leyendas de figura

Las leyendas son resúmenes concisos y completos de una figura. La leyenda y el número de figura son opcionales. Si usas figcaption, envuelve img y figcaption en un figure para que la leyenda quede asociada a la imagen.

• Si numeras, usa la forma «Figura N. Descripción.»
• Recomendamos oraciones completas en la leyenda.
• Cierra siempre la leyenda con puntuación.
• Al referirte a una figura, no uses descripciones espaciales como «la imagen de arriba».
• Si numeraste, refiérete a la figura por su número de forma consistente: «… como muestra la figura 1». No escribas «figura» con mayúscula en la referencia salvo al inicio de oración.
• Si no puedes numerar, vuelve a mostrar la figura, por accesibilidad y experiencia de uso.
• No metas la leyenda dentro de la oración que refiere a la figura.

Descripciones de figura

Una descripción de figura es el texto que explica con más detalle la información que la figura representa: lo que dice la imagen queda capturado en texto. La información nueva va siempre en texto, nunca solo en una figura.

• Escribe texto que transmita la misma información que la figura.
• Úsala cuando la leyenda no alcanza para el propósito o la información completa de la figura.
• Usa puntuación.

Texto dentro de las figuras

Evita incrustar texto explicativo en las capturas: daña la accesibilidad y la búsqueda, y encarece la traducción si la figura se localiza. Si debes incrustarlo, da la misma información en una forma que una persona con discapacidad visual pueda usar, como una descripción de figura. Cuando el texto en la figura es inevitable:

• Sé breve. Evita oraciones completas y puntuación cuando puedas.
• No incrustes leyendas ni descripciones en la imagen; ponlas en el texto que la sigue.
• No inventes abreviaturas para condensar.
• Usa minúscula de oración, la misma regla de Títulos y encabezados.
• Usa llamadas numeradas para apoyar la descripción de figura, no para anotaciones detalladas dentro de la imagen.
• Usa los nombres de producto completos y con su marca.

Recursos de accesibilidad

• Web Content Accessibility Guidelines (WCAG).
• Guía general de alternativas textuales de WCAG.
• Uso del atributo alt en img.
• Descripción larga en texto cercano al contenido no textual.
• Imágenes complejas.

Imágenes de alta resolución

Los navegadores modernos usan imágenes de alta resolución si están disponibles, y se ven mejor en pantallas densas. Para ofrecerlas, usa el atributo srcset del elemento img además del src estándar. srcset acepta una lista de URL separadas por coma, cada una con un calificador de densidad: 1x es la resolución estándar, 2x el doble, y así.

Si el navegador soporta srcset, elige la imagen que mejor calza con la pantalla. Si no, usa la de src. Por eso src es obligatorio siempre. Ejemplo con resolución simple y doble:

<img src="/img/panel.png"
     srcset="/img/panel.png 1x,
             /img/panel_2x.png 2x"
     width="375" alt="">

• El atributo width coincide con el tamaño en píxeles CSS de la página. La altura se calcula sola a partir del ancho y la proporción; no la declares.
• Apunta src a la versión estándar (1x), no a la 2x. Casi toda pantalla densa viene con un navegador que entiende srcset; src lo usan sobre todo navegadores viejos en pantallas de baja resolución, que deben bajar la imagen chica. Aunque tu original sea el de alta resolución, no obligues a quien no lo puede ver a descargarlo.
• El nombre del archivo doble puede ser cualquiera (lo que informa la densidad es el «2x» que lo sigue), pero conviene la forma BASE_2x.EXT para que un humano lo reconozca.
• La imagen doble debe medir exactamente el doble de ancho y alto que la estándar, con un píxel de tolerancia (875x500 contra 438x250 está bien).
• No amplíes una 1x para fabricar la 2x. Si solo tienes 1x, úsala sola. Si partes de alta resolución (2x o más), reduce para obtener 1x y 2x.
• Hoy basta con 2x, pero la densidad de las pantallas puede subir; srcset admite 3x, 4x y más.
• Un navegador que entiende srcset ignora src. Declara todas las resoluciones disponibles en srcset.

Nota: si revisas una imagen con frecuencia, puedes usar la 2x en src y en srcset en vez de mantener dos tamaños. Cuando se estabilice, agrega la 1x.

Disposición de las imágenes en la página

• No ubiques la imagen a mano: nada de style ni trucos para la alineación o los márgenes. Usa los estilos de imagen estándar del kit.
• No la hagas demasiado chica. Está bien que ocupe todo el ancho de la columna.
• Piensa cómo se verá impresa.
• No uses una imagen más ancha que la columna donde aparece. Mira el ancho de columna en base/tokens.css del kit; la versión 2x mide el doble de ese ancho.
• Las capturas a resolución completa suelen ocupar demasiado; redimensiónalas.
• Si el gráfico lo hizo otra persona, pídele la pareja 1x/2x al ancho correcto; para quien tiene el original suele ser trivial.
• No enlaces a la figura desde la misma página salvo que la página sea muy larga y el enlace venga de lejos.
• No centres la imagen.
• No pongas un img dentro de un p.

Notas al pie

Una nota al pie es una anotación con información adicional, normalmente al final de una página, capítulo o libro. Evítalas: no son accesibles y complican la traducción. En vez de una nota al pie, usa uno de estos formatos:

• Agrega una referencia cruzada.
• Usa un aviso (ver Notas y avisos).
• Ponlo entre paréntesis.

Si la única forma de transmitir la información es una nota al pie, usa un número en superíndice, por ejemplo <sup>1</sup>. Los informes largos del grupo (el informe CIF-EP, los anexos) sí usan notas al pie por exigencia editorial; ahí el motor de render las gestiona y no aplica esta restricción web.

Títulos y encabezados

Usa minúscula de oración en títulos y encabezados: solo la primera palabra y los nombres propios llevan mayúscula (norma P37). Usa encabezados descriptivos y únicos: ayudan al lector a moverse por el navegador y por la página, y es más fácil saltar entre secciones si cada título es distinto.

Texto del título y del encabezado

Escribe el título del documento según su propósito principal. Si un documento es sobre todo un tutorial pero tiene una introducción conceptual, escribe un título de tarea. Escribe el encabezado de cada sección según el tipo de contenido de esa sección.

Redacción del título

Usa un único encabezado de nivel 1 (h1) por página dentro de un conjunto de documentos, y úsalo una sola vez en la página. Evita repetir el título exacto de la página en un encabezado interior. Si documentas cómo crear y cómo iniciar una máquina virtual en la misma página de tarea, el título puede ser «Crear e iniciar instancias» y las secciones «Crear una instancia» e «Iniciar una instancia».

Estilos mezclados

Está bien combinar encabezados de tarea y conceptuales en un mismo documento. Si un documento tiene secciones de ambos tipos, usa la forma que corresponde a cada sección.

Uso del gerundio

Cuando puedas, evita el gerundio como primera palabra de un encabezado o título. El gerundio se traduce de forma inconsistente al encabezar y ocupa más caracteres donde el espacio es escaso. En español, además, el gerundio en un título suele ser un calco del inglés («Configurando el servidor»).

A veces no hay mejor alternativa que un sustantivo derivado, como «Facturación» o «Precios»; está bien. También está bien un gerundio más adelante en el título, como «Introducción al monitoreo en ejecución».

Ejemplo de encabezados

El siguiente ejemplo es un documento de tarea con un encabezado conceptual y uno de tarea.

<h1>Registrar las facturas recibidas con el poller DTE</h1>
<p>Este documento de tarea muestra cómo registrar las facturas que llegan
por el intercambio del SII. El título empieza con infinitivo.</p>

<h2>Panorama del intercambio DTE</h2>
<p>Esta sección da una visión conceptual del flujo. Su título es un
sintagma nominal.</p>

<h2>Configurar el acuse en cis-admin</h2>
<p>Esta sección de tarea da una serie de pasos. Su título empieza con
infinitivo.</p>

En Markdown:

# Registrar las facturas recibidas con el poller DTE

Este documento de tarea muestra cómo registrar las facturas que llegan por el intercambio del SII. El título empieza con infinitivo.

## Panorama del intercambio DTE

Esta sección da una visión conceptual del flujo. Su título es un sintagma nominal.

## Configurar el acuse en cis-admin

Esta sección de tarea da una serie de pasos. Su título empieza con infinitivo.

Formato del título y del encabezado

En general, lo que vale para el texto corriente vale para los encabezados: apócopes, artículos, acentos.

Sintaxis y mayúsculas

• Usa minúscula de oración en todos los títulos y encabezados. El Title Case («Impacto de la Tecnología en la Salud») es un anglicismo y la norma lo marca (P37). Ver Mayúsculas.
• Puntuación simple. La puntuación en un encabezado suele avisar que el encabezado es demasiado complejo. Reescribe. Nunca una raya (P05); si necesitas separar dos partes, usa «·» o dos puntos.
• Limita las abreviaturas. Usa una sigla en un título solo si es la forma más conocida del término (SII, DTE, API). Si la usas, defínela en la primera aparición en un párrafo. Puedes definirla en el título, pero evalúa si el largo extra aporta. Para buscadores, usa en el título la forma más prominente del término. Ver Abreviaturas.

Formato y código

• No numeres los encabezados para indicar secuencia. La jerarquía y el orden la indican solos.
• Evita elementos de código en los encabezados. Si debes mencionar uno, agrégale un sustantivo descriptivo junto al término en fuente de código. Ver Código en el texto.
• No pongas enlaces en los encabezados. Se confunden con un estilo aplicado al encabezado.

Jerarquía y estructura

• No uses etiquetas de encabezado para cambiar el aspecto. Usa CSS, no un nivel que no calza en la jerarquía. No inventes formatos propios para encabezados.
• Aplica las etiquetas correctas. Estructura el contenido con <h1>, <h2>, <h3> en HTML o #, ##, ### en Markdown.
• Mantén el orden lógico. No saltes niveles: un <h3> solo va bajo un <h2>.

<h1>Transferir conjuntos de datos</h1>
<p>Este documento resume las formas de mover datos al lago.</p>
<h2>Estimar costos</h2>

<h1>Transferir conjuntos de datos</h1>
<p>Este documento resume las formas de mover datos al lago.</p>
<h3>Estimar costos</h3>

• No dejes encabezados vacíos. Todo encabezado va seguido de contenido antes del siguiente.

<h2>Migrar servicios a vps-cis</h2>
<p>La migración no es un solo paso. Las siguientes secciones describen
los pasos recomendados.</p>
<h3>Diseñar la migración</h3>

<h2>Migrar servicios a vps-cis</h2>
<h3>Diseñar la migración</h3>

Referirse a un grupo de secciones

Si introduces un grupo de secciones H3 o inferiores dentro de una sección H2 mayor, usa la frase «las siguientes secciones». No uses «esta sección» ni «estas secciones»: son ambiguas.

<h2>Vistas del editor de asientos</h2>
<p>Las siguientes secciones describen las vistas del editor de asientos.</p>
<h3>Vista de datos</h3>
<p>…</p>
<h3>Vista de gráfico</h3>
<p>…</p>
<h3>Vista de esquema</h3>
<p>…</p>

Cursivas en términos

Este tema describe dos casos en que se usa cursiva para términos que se introducen o se discuten. Para la cursiva en general, incluido su marcado en HTML y Markdown, ver Resumen de formato de texto.

Términos nuevos

Cuando introduces un término nuevo que defines de inmediato, ponlo en cursiva la primera vez. No uses negrita ni comillas.

Palabras como palabras

Cuando te refieres a una palabra, frase o letra en cuanto tal (a veces llamado palabras como palabras), usa cursiva. No uses negrita ni comillas.

Extranjerismos

Regla de la casa: el extranjerismo crudo (deploy, pipeline, release) va en cursiva si decides conservarlo, pero antes pregúntate si hace falta (Orwell 5 y norma P07: un significante, un significado). Si el glosario del repo tiene el equivalente («despliegue», «canalización», «versión»), usa el equivalente y sin cursiva. Los nombres de comando y de servicio (deploy-cis, cis-build) van en fuente de código, no en cursiva.

Listas

Las listas y las tablas son dos formas de presentar un conjunto de ítems de estructura parecida. Para decidir cuál usar, ver Tablas, apartado «¿Lista o tabla?». No uses una lista para un solo ítem: un ítem solo no es una lista. Si quieres destacarlo, usa otro formato.

Tipos de lista

La siguiente tabla recoge las formas habituales de presentar listas en la documentación del grupo:

Ítems con varios párrafos

Cualquier ítem puede tener más de un párrafo. Para crearlos usa el elemento p, no br (la especificación de HTML define qué usos de br son legítimos y cuáles no).

• Este ítem es un solo párrafo.

• Este ítem tiene varios párrafos.

  Como se ve.

• Este es otro ítem de un párrafo.

Oraciones introductorias

Introduce la lista con el contexto que corresponda. Casi siempre una lista va precedida por una oración introductoria. La oración termina en dos puntos si la lista la sigue de inmediato y en punto si hay material entre medio (una nota). Si la lista no necesita más contexto que el encabezado que la precede, puedes omitir la introducción.

Introduce la lista con una oración completa, no con un fragmento que los ítems completan. «Lo siguiente» puede funcionar como sintagma nominal.

Para introducir subpasos, ver Procedimientos. Para la puntuación y las mayúsculas de las listas, ver «Mayúsculas y puntuación final» en este tema.

Numeración inusual

• Para presentar una lista en orden numérico inverso, usa ol con el atributo reversed.
• Para fijar un valor a mano, usa el atributo value. A veces conviene, pero en general numerar a mano es mala idea: si la cantidad de ítems cambia, hay que corregir los valores uno a uno.

Subpasos en un procedimiento numerado

Ver Procedimientos.

Sintaxis paralela

Usa la misma sintaxis y estructura en todos los ítems de una lista cuando sea posible.

Mayúsculas y puntuación final

Dependen del tipo de lista y de su contenido.

Listas numeradas, con letras y con viñetas

Empieza cada ítem con mayúscula, salvo que la caja sea parte de la información (una lista de términos de glosario). Cierra cada ítem con punto u otra puntuación de fin de oración, salvo en estos casos:

• Si el ítem es una sola palabra, no agregues puntuación final.
• Si el ítem no tiene verbo, no agregues puntuación final.
• Si el ítem va entero en fuente de código, no agregues puntuación final.
• Si el ítem es solo texto de enlace o título de documento, no agregues puntuación final.

Si te queda una puntuación inconsistente, reescribe la lista con construcción paralela o agrega puntuación final a todos los ítems.

Listas de descripción

A veces conviene agregar una frase explicativa a un ítem, y eso afecta la puntuación. En general, no agregues explicación a un solo ítem; usa una lista de descripción y explica todos. En casi todo contexto, empieza cada término (dt) con mayúscula y no lo cierres con punto. Cierra cada descripción (dd) con punto.

Listas de descripción con encabezados en línea

En casi todo contexto, formatea los encabezados en línea así:

• Empieza el encabezado con mayúscula.
• Ciérralo con punto o con dos puntos, pero sé consistente dentro de la lista.
• Puedes decidir si la puntuación de cierre va en negrita según la consistencia de la página.

Para la descripción que sigue a la puntuación, la mayúscula inicial va así:

• Si sigue a un punto, empieza con mayúscula.
• Si sigue a dos puntos, empieza con minúscula.

Para cerrar la descripción:

• Si sigue a un punto, cierra con punto.
• Si sigue a dos puntos: si es una lista de ítems o frases cortas sin verbo, sin punto; si tiene verbo o expresa una idea completa, con punto.

No uses raya ni guion para separar la descripción del término (P05). Usa dos puntos. Ver Dos puntos.

Nota: estas reglas de puntuación son para prosa documental. Si escribes texto de interfaz, sigue las reglas de copy de UI del kit.

Listas separadas por comas

Cuando escribes una lista dentro de un párrafo, separa los ítems con comas y no pongas coma antes de la «y» final: la coma serial es una convención del inglés. Ver Comas.

Evita cerrar una lista con «etc.» o «y así sucesivamente». Introduce la lista de modo que quede claro que no es exhaustiva.

Notación matemática

Este tema describe cómo dar formato a la notación matemática común (exponentes, expresiones, ecuaciones, operadores, variables) en la documentación. Un buen formato hace que el contenido sea compatible con tecnologías de asistencia y se renderice bien. Para el uso general de números, ver Números.

Nota: los ejemplos son de HTML y Markdown en texto corriente. Si usas una herramienta de terceros para matemática compleja (MathJax, KaTeX, Typst en los informes del grupo), sigue la guía de esa herramienta.

Entidades HTML para símbolos matemáticos

En general, usa entidades HTML para los símbolos matemáticos en vez de los símbolos del teclado. Para más (+), igual (=) y la barra de división (/) puedes usar la tecla.

Formato de la notación

Operadores

Para accesibilidad y sintaxis HTML correcta, usa entidades en vez de teclas para los operadores: − en vez de un guion (-). Pon un espacio duro ( ) a ambos lados de cada operador dentro de una misma expresión, ecuación o enunciado. No pongas los operadores en cursiva.

Variables

Pon las variables en cursiva.

Expresiones y ecuaciones

Las expresiones y ecuaciones cortas van en línea con el texto. Pon espacios duros entre los componentes (operadores y variables) para que no se partan entre líneas. Si una expresión produce un corte de línea incómodo, ponla en su propia línea.

Fracciones

Expresa las fracciones como decimales cuando puedas. En español el decimal se separa con coma. Si debes escribir la fracción en palabras, escríbela sin guion (el guion entre numerador y denominador es una regla del inglés).

En código, JSON, URL y salidas de comando, el punto decimal se conserva tal como lo produce la máquina: 0.02.

Exponentes y subíndices

Usa la notación matemática estándar. No dejes espacio entre la base y el exponente. Para exponentes usa la etiqueta <sup>; no uses el acento circunflejo (^). Para subíndices usa <sub>.

Notación en lugar de palabras

En general puedes usar notación matemática en vez de palabras en texto corriente: x ≠ y en vez de «x es distinto de y». Si la notación produce un texto ambiguo, gramaticalmente incorrecto o difícil de leer, usa palabras.

Herramientas para ecuaciones complejas o de varias líneas

Las entidades y etiquetas de este tema sirven para la notación común. Para ecuaciones complejas, de varias líneas o difíciles de representar en HTML plano, considera diagramas, imágenes o un motor de render matemático. Los informes del grupo que se componen en Typst o LaTeX usan el modo matemático del motor. Para comparar estadísticas e ilustrar porcentajes, un gráfico de barras suele ayudar más que una fórmula; antes de hacerlo, lee la guía de visualización del hub.

Más recursos

• Números
• Unidades de medida
• Resumen de formato de texto

Notas y avisos

Para dar al lector información importante o útil que no forma parte del flujo del texto, puedes destacarla en un aviso. Hay evidencia de que los lectores saltan los elementos fuera de su foco, incluidos los avisos. Si dudas de si algo merece aviso, escríbelo primero como texto corriente y después decide.

No abuses de los avisos. Con varios en una página pierden distinción visual. Busca otra forma de transmitir la información, sobre todo si te quedan dos o más seguidos. Evita agrupar avisos (una nota con una precaución adentro, varias advertencias en fila); si te pasa, reorganiza el contenido.

Elegir el tipo de aviso

Nota

Un aparte o consejo ordinario. Información útil pero no crítica. Por ejemplo: «Generar tráfico excesivo hacia sistemas externos puede parecer un ataque de denegación de servicio».

Precaución

Pide al lector que proceda con cuidado. Por ejemplo: «No recomendamos un rango amplio 0.0.0.0/0 que deje pasar todo el tráfico».

Advertencia

Más fuerte que la precaución: significa «no hagas esto» o que el paso puede ser irreversible, como una pérdida permanente de datos. Si el lector la ignora, puede perder dinero, perder trabajo o abrir una brecha de seguridad. Por ejemplo: «No pongas la contraseña en la línea de comandos: queda en el historial».

Éxito

Describe una acción exitosa o un estado sin errores. Solo en contenido interactivo o dinámico; no en páginas estáticas. Por ejemplo: «Desplegaste cis-admin en vps-cis».

Regla de la casa para runbooks y manuales de operación (modo estricto de la norma, tomado del ETS): PELIGRO es daño a personas, PRECAUCIÓN es daño al equipo o a los datos, NOTA es información y nunca contiene órdenes. En los tres, la orden va primero y la explicación después.

Cuándo usar una nota

Crea una nota cuando se cumplen las tres condiciones:

• La información es relevante pero no necesaria para lo que el lector hace ahora. Si la salta, igual tiene éxito.
• Interrumpir al lector en ese punto no le estorba. Tu nota no sugiere una alternativa que lo lleve por otro camino.
• La información no es parte del flujo de lo que escribes: no es una continuación, un resultado ni un puntero a más información.

Cuándo no usar una nota

• No uses notas para referencias cruzadas.
• No uses notas para avisar de requisitos previos o de pasos que el lector debió dar antes. Eso va antes del paso.
• No conviertas un paso completo de procedimiento en nota.
• No uses notas para información necesaria para tener éxito.
• No uses notas para información que sigue el flujo del texto anterior: no pongas en nota el resultado esperado ni una descripción de lo que precede.

Ejemplos

Usa la presentación visual estándar del sitio. El kit v9 no trae un componente de aviso. Si escribes HTML y tu sitio no fija uno, usa un marcado como el siguiente, con borde uniforme de 1 px en var(--line).

El borde izquierdo de color (la barrita de acento) está prohibido en todo sitio del grupo (CANON, decisión del 2026-08-06). La jerarquía se hace con fondo, tipografía o una etiqueta en mono.

<aside class="aviso aviso--nota"><b>Nota:</b> todas las redes VPC incluyen reglas de firewall.</aside>

• Nota: todas las redes VPC incluyen reglas de firewall.
• Precaución: no recomendamos una subred que sea parte de una ruta dinámica.
• Advertencia: no edites ni borres a mano las entradas generadas en la tabla.
• Éxito: creaste la instancia.

Números

Para cantidades con unidad, como 10 MB, ver Unidades de medida. Regla transversal de la casa: miles con punto, decimales con coma, y la cifra antes que la interpretación (data-forward, norma «Juicio» 1).

Ordinales

Escribe los ordinales en palabras en el texto. En tablas y referencias legales (artículos, cláusulas) está bien la forma abreviada con letra volada: 1.º, 2.ª.

Números en palabras

Si importa que el número y su sustantivo queden en la misma línea, pon un espacio duro entre ambos. En general, escribe en palabras:

• Los números de cero a nueve, salvo las excepciones de «Números en cifras».

• El número que empieza una oración. A veces conviene reordenar la oración para que el número aparezca después.

Excepción: está bien, aunque no es óptimo, empezar una oración con un año de cuatro cifras.

• El número que va seguido de una cifra.

• Los números indefinidos o coloquiales. «Millones» o «miles» está bien para aproximaciones. Para números precisos, cifras.

Números en cifras

Si importa que el número y su sustantivo queden en la misma línea, pon un espacio duro entre ambos. En general, usa cifras para:

• Los números de 10 en adelante.

Excepciones: usa siempre cifras para lo siguiente, aunque sea menor que 10:

• Números de versión: versión 3.
• Cantidades técnicas: memoria, disco, consultas, límites de uso: 6 consultas por segundo, 50 Mbps, 128 bits.
• Números de página.
• Números de capítulo, sección y similares.
• Números de paso. Evita referirte a pasos por número; si no hay alternativa, usa la cifra.
• Precios.
• Números sin unidad, como los de una expresión matemática.
• Números menores que 10 en una oración con números mayores que 9: «El menú tiene 15 opciones y 6 están desmarcadas».
• Números negativos.
• La mayoría de las fracciones.
• Porcentajes.
• Dimensiones.
• Números con decimales. Trata los decimales como plural aunque sean menores o iguales a 1,0: «1,0 pulgadas». Para decimales menores que uno, pon el cero antes de la coma: «0,3 pulgadas».
• Medidas: 8 píxeles.
• Números en un rango.

Números romanos

Evita los números romanos cuando puedas; los arábigos se escanean más rápido. Puedes usar romanos en minúscula para subpasos de un procedimiento numerado. En documentos legales del archivo (cláusulas, títulos de escritura) se respeta la numeración del instrumento original.

Fracciones

Expresa las fracciones como decimales cuando puedas. Si debes escribirlas en palabras, sin guion.

Porcentajes

Usa cifras y el signo de porcentaje, sin espacio entre ambos. La RAE prefiere el espacio («40 %»); la casa lo cierra («40%») y así está escrito el corpus del grupo. Excepción: si el porcentaje empieza la oración, escribe en palabras el número y la palabra «por ciento».

Rangos de números

Usa guion sin espacios. No uses semirraya (–) ni raya. En prosa corrida también sirve «de 2012 a 2016».

Para rangos con unidad, ver Unidades de medida.

Guiones suspendidos

El inglés usa guiones suspendidos («one-, two-, or three-hour intervals»). El español no compone así; repite la estructura o usa «de … , … o …».

Moneda

Deja claro de qué moneda hablas. En el grupo, «$» a secas es peso chileno; si en la misma página aparece otra moneda, escribe «CLP» o «US$» y «UF» según corresponda. Para pesos, separa los miles con punto y no uses decimales salvo en precios unitarios. Pon el signo al inicio, sin espacio. No pongas puntuación ni espacios a la derecha de los decimales.

Más en Unidades de medida.

Puntos y comas en los números

Usa el formato de es-CL: en números de cuatro o más cifras, separa los grupos de tres con punto contando desde la coma decimal hacia la izquierda. En decimales largos no uses separador a la derecha de la coma. Usa coma como separador decimal. Los años no llevan separador (2026, no 2.026). Nota: el Sistema Internacional usa un espacio fino como separador de miles; la casa usa el punto, que es lo habitual en Chile. Aunque en escritura científica los números de cuatro cifras suelen ir sin separador, la casa lo pone.

En código, JSON, URL, CSV y salida de comandos se conserva el formato de la máquina (punto decimal, sin separador de miles): 1532784, 0.031611. No «traduzcas» una salida de terminal.

Dimensiones

Usa cifras. Entre las cifras va una x minúscula sin espacios.

Exponentes

Usa la notación estándar. No dejes espacio entre la base y el exponente: 2³. Ver Notación matemática.

Acompaña los números con su implicación práctica

Dale a la cifra un significado tangible. Si una función genera un cobro, enlaza la calculadora de precios; si un umbral dispara una acción, di cuál.

Notación matemática y gráficos

Para ecuaciones y variables, ver Notación matemática.

Párrafos

Parte los párrafos para que la página se pueda escanear y no sea un muro de texto. La gente escanea y lee en pantallas de distinto tamaño. Cada párrafo trata una sola idea con las menos palabras y las menos oraciones posibles. No alargues las oraciones para reducir la cuenta de oraciones: oraciones cortas y párrafos cortos.

Un párrafo de más de 5 o 6 oraciones suele avisar que intenta decir demasiado; pártelo o quita contenido. La norma de la casa lo mide: avisa a las 8 oraciones en modo prosa y a las 6 en modo estricto (P12), y a las 40 palabras por oración en prosa y 25 en estricto (P11). No partas un párrafo que trata una sola idea: un párrafo de una oración está bien, y uno de más de 6 puede estar bien si sigue siendo una sola idea.

Lo crítico primero

Igual que en la oración, pon lo más importante al inicio del párrafo. No escondas la idea central al final: el lector no lee cada palabra. Es la misma regla data-forward de la norma («Juicio» 1): la cifra o el hecho primero, la interpretación después.

Formato de los párrafos

Alinea el texto a la izquierda. No centres, no justifiques ni alinees a la derecha en la web. Los documentos impresos de Firmas y Documentos justifican por su plantilla; es la excepción del formato legal, no la regla.

No fuerces saltos de línea dentro de oraciones y párrafos. Los saltos forzados fallan al cambiar el ancho de la ventana, el dispositivo o el tamaño de letra.

Teléfonos

Este tema describe cómo usar y formatear teléfonos en la documentación. No trata cómo ingresar teléfonos en un producto; para eso, la documentación del producto.

Teléfonos de ejemplo

La mayoría de los teléfonos en la documentación son ejemplos. Chile no reserva un rango para ficción. Usa el marcador TELEFONO o, si el ejemplo necesita un número con forma real, el rango estadounidense reservado para ficción, 800-555-0100 a 800-555-0199, en formato internacional, y dilo. Nunca uses un número real: ni el tuyo, ni el de un socio, ni uno sacado de una guía.

Formato en HTML y Markdown

Para que el número no se parta entre líneas, usa espacio duro ( ) entre los grupos. Si el formato lleva guion, usa guion duro (‑).

Teléfonos de Chile

Para un teléfono real en Chile, usa el formato internacional de la UIT con el código de país: +56, el código de zona o el 9 de los móviles, y el número en grupos de cuatro. El signo más va pegado al código de país; reemplaza el prefijo de salida, que cambia según el país desde donde se marca.

Teléfonos de Norteamérica

Para un teléfono real de Estados Unidos, Canadá y los demás países del plan norteamericano, antepón +1. Separa con guion duro el código de área, el código de central de tres cifras y el número de cuatro cifras.

Teléfonos internacionales

Para un teléfono real de otro país, incluye el código de país y el de zona. El signo más va inmediatamente antes del código de país, sin espacio. Ver el documento de la UIT sobre formato normalizado de números.

Teléfonos con anexo

Para indicar un anexo, escribe el número, coma, la palabra «anexo» y el número del anexo. En Chile se dice «anexo», no «extensión».

Procedimientos

Un procedimiento es una secuencia de pasos numerados para cumplir una tarea. Para listas que no son procedimiento, ver Listas.

Regla de la casa que va más lejos que Google: los procedimientos, runbooks, mensajes de error y copy de UI se escriben en el modo estricto de la norma. Eso fija la orden en infinitivo-imperativo («Examinar todo el sistema», no «Examine» ni «Examina»; P29), 25 palabras por oración como tope (P11), sin gerundio (P25), sin subjuntivo (P26), sin punto y coma (P31) y en voz activa (P30).

Una guía de usuario escrita en tú puede usar el imperativo de tú («haz clic»), pero no se mezclan los dos registros en un mismo documento.

Oraciones introductorias

Casi siempre, introduce el procedimiento con una oración que dé un contexto que el encabezado no da. No repitas el encabezado: si el encabezado ya explica qué hace el procedimiento y no hace falta más contexto, omite la introducción. La oración termina en dos puntos si el procedimiento la sigue de inmediato y en punto si hay material entre medio (una nota). Puedes introducir con una orden. No introduzcas con un fragmento que los pasos completan.

Procedimientos de un paso

Cuando el procedimiento tiene un solo paso, escríbelo en una oración con viñeta.

Subpasos en procedimientos numerados

En un procedimiento numerado, los subpasos se rotulan con letras minúsculas y los sub-subpasos con números romanos en minúscula. Cuando un paso tiene subpasos, trátalo como oración introductoria: dos puntos o punto al final, según corresponda.

Orden de los componentes de un paso

Para documentar un paso complejo, usa este orden:

1. Describir la acción.
2. Dar el comando, si hace falta.
3. Explicar los marcadores de posición del comando. Ver Formato de marcadores de posición.
4. Explicar el comando con más detalle, si hace falta.
5. Mostrar la salida del comando, si hace falta.
6. En un párrafo aparte, explicar el resultado de la acción o la salida, si hace falta.

El siguiente ejemplo sigue ese orden:

1. Leer el secreto del proyecto:

   vault get PROYECTO CLAVE

   Reemplazar PROYECTO por el nombre del repo y CLAVE por el nombre de la variable.

   El comando vault get hace lo siguiente:

   • Se conecta al core-server illanes00.
   • Busca la clave dentro del espacio del proyecto.
   • Imprime el valor en la salida estándar, sin salto final.

   La salida es similar a la siguiente:

   re_4Kx…9Qz

   La salida es el valor vivo; no lo pegues en un archivo versionado.

Procedimientos de varias acciones

En general, un paso por acción. Puedes combinar acciones pequeñas en un paso usando el signo mayor que (>) para selecciones de menú secuenciales. No alargues los pasos; si se sienten largos, pártelos.

Varios procedimientos para la misma tarea

Si hay más de una forma de cumplir una tarea, documenta una que sea accesible para todos los lectores. Si todas lo son, elige la más corta y simple. Si debes documentar varias, sepáralas en páginas, encabezados o pestañas distintas. Para elegir:

• Elige un procedimiento que se pueda completar solo con teclado.
• Elige el más corto.
• Elige el que usa el lenguaje de programación que más conoce tu audiencia.

Procedimientos repetitivos

No repitas procedimientos. Refiérelos y enlázalos.

Pasos opcionales

Para un paso opcional, escribe «Opcional» y dos puntos al inicio del paso. Para secciones opcionales, ver Títulos y encabezados.

Pasos que dicen dónde se hace la tarea

Di dónde se hace la acción (una herramienta, un campo de la interfaz) antes de la acción. Si un conjunto de procedimientos está repartido en varios encabezados, repite en cada procedimiento dónde se hace. Si dos procedimientos ocurren en la consola, ambos empiezan con «En la consola…».

Pasos con objetivo

En algunos pasos conviene decir el objetivo. Cuando el paso incluye un objetivo, el objetivo va antes de la acción: así el lector entiende y completa el paso con menos esfuerzo.

A veces ese formato sugiere que el paso es opcional. En esos casos, usa dos puntos:

Dentro de un procedimiento suele ser claro si un paso es obligatorio; ahí el formato «Para…» es más natural que los dos puntos. Para decidir, mira cómo se relaciona el objetivo del paso con el objetivo del procedimiento.

En un procedimiento para crear un gráfico de barras, el paso con objetivo «Para crear el gráfico» es obligatorio sin duda. «Para mejorar el gráfico» tampoco confunde. Pero «Para ordenar los datos por fecha» puede ser o no necesario. Para dejar claro que no es opcional, usa «Ordenar los datos por fecha:».

Pasos con resultado o justificación

Algunos pasos son una acción más la reacción que orienta al lector hacia el siguiente paso. Primero la acción y después el resultado, en el mismo párrafo. Considera además si puedes evitar la repetición y el exceso de negrita en los nombres de interfaz.

Para describir salidas, ver Sintaxis de línea de comandos. Otros pasos mejoran con una justificación de por qué importan. Primero la acción, después la justificación.

Resumen de la guía para escribir procedimientos

Tablas

En muchos contextos, la tabla es la mejor forma de representar conjuntos de datos relacionados. En otros, hay mejores opciones.

¿Lista o tabla?

Las listas y las tablas presentan conjuntos de ítems de estructura parecida, y no siempre es obvio cuál elegir. Consulta la siguiente tabla:

Dónde no usar tablas

• No uses tablas para maquetar la página; usa el CSS del kit.
• Si tienes una sola fila, la tabla no suele ser la mejor forma. En algunos contextos (consistencia en documentación de referencia) puede serlo.
• Si tienes una sola columna, convierte la tabla en lista.
• No uses tablas para maquetar fragmentos de código.
• No uses tablas para repartir en columnas una lista larga de una dimensión. Si tienes una lista larga de nombres de función, no la partas en dos mitades para ahorrar espacio. La tabla es para datos bidimensionales: material que tiene sentido en filas y columnas.
• Evita tablas en medio de un procedimiento numerado.

Celdas con varios párrafos

Cualquier celda puede tener más de un párrafo. Usa el elemento p, no br.

Oraciones introductorias

Introduce la tabla con una oración completa que describa su propósito, porque no todos los lectores de pantalla anuncian las tablas. La oración termina en dos puntos si la tabla la sigue de inmediato y en punto si hay material entre medio. Ver también Accesibilidad.

Ubicación de la tabla

• Al introducir una tabla, usa una oración completa y refiere su posición con «la siguiente tabla» o «la tabla anterior».
• No pongas una tabla en medio de una oración.
• Evita notas al pie. Si la tabla las necesita, ponlas inmediatamente después de la tabla. Ver Notas al pie.

Leyendas de tabla

Si el documento tiene una sola tabla, no necesita leyenda; ponla junto al texto que la refiere. Si hay varias tablas cerca, dale a cada una una leyenda con el elemento caption como primer hijo de table. Empieza con el número, en la forma «Tabla N. Descripción». Usa minúscula de oración y no cierres con punto.

Al referirte a la tabla desde el texto, usa el número: «… como muestra la tabla 2». No escribas «tabla» con mayúscula salvo al inicio de oración. El CSS del sitio decide el estilo y la posición de la leyenda.

<table class="table">
  <caption><b>Tabla 1.</b> Aves prehistóricas</caption>
  …
</table>

<p><b>TABLA 1: AVES PREHISTÓRICAS.</b></p>
<table>…</table>

Formato de la tabla

• No agregues estilos al elemento table. En el kit usa class="table", y table--num cuando las columnas son numéricas.
• No uses fuente, color ni fondo distintos para señalar una fila o columna de encabezado. Usa th para marcar los encabezados semánticamente.
• No combines celdas. No uses colspan ni rowspan.
• Ordena las filas con un criterio lógico, o alfabético si no lo hay.
• Si la tabla es larga o compleja (varias filas o columnas de encabezado), considera partirla en varias.
• No presentes información nueva solo con imágenes o símbolos; da siempre un alt descriptivo. Ver Figuras e imágenes.

Encabezados de columna

• Usa minúscula de oración.
• Escribe encabezados concisos.
• No cierres con puntuación: ni punto, ni puntos suspensivos, ni dos puntos.
• Usa encabezados solo en la primera columna y la primera fila, con th.
• Incluye el atributo scope que corresponda, por accesibilidad.

Tablas adaptables

Cuando puedas, usa el CSS de tabla que se adapta a distintos anchos de pantalla. El kit lo trae en .table.

Enlaces a tablas

Cuando puedas, evita enlazar a una tabla; refiérela por su número.

Unidades de medida

Pon un espacio duro ( ) entre el número y la unidad.

Espacios en las unidades

Para la mayoría de las unidades, cuando das un número con su unidad, usa un espacio duro entre ambos, en HTML y en Markdown. Para cuándo escribir la unidad con todas sus letras, ver Abreviaturas. Para cuándo usar guion, ver Guion.

En español, «un sistema de 128 bits» se escribe con preposición, sin el guion compuesto del inglés.

Para el plural de las abreviaturas, ver Plurales.

Cuando la unidad es dinero, porcentaje o grados de ángulo, no uses espacio. Ver «Moneda» más abajo.

Para grados de temperatura, pon un espacio duro entre el número y el símbolo de grado, y ningún espacio entre el símbolo (°) y la escala (C o F). Para Kelvin, sin símbolo de grado y con espacio duro antes de la K.

Cuando número y unidad modifican juntos a un sustantivo, en español van con «de» y sin guion.

Rangos de números con unidad

En un rango, repite la unidad en cada número. «Unidad» incluye símbolos (el de grado) y abreviaturas (MB), pero no sustantivos (archivo). Usa «a» entre los números en vez de guion: el guion se puede leer como signo menos. Ver también Números.

Guion en unidades multiplicadas

Cuando los componentes de una unidad se multiplican entre sí, únelos con guion.

Uso de «k» para miles

En algunos contextos (tablas, interfaz, paneles) se puede indicar miles con una k minúscula después del número. Si lo haces: sin espacio entre el número y la k, y con un sustantivo que diga qué mide el número, para que no se lea como kilobytes. En prosa, la casa prefiere «55 mil».

Moneda

Si escribes sobre dinero, el lector tiene que saber de qué moneda hablas. El signo «$» puede ser peso chileno, dólar estadounidense, dólar canadiense o peso mexicano. En el grupo, «$» sin calificar es peso chileno. Si hay cualquier posibilidad de ambigüedad, pon el indicador de moneda antes del monto: «US$», «CLP», «UF». Para el detalle, el Manual de Chicago, 17.ª edición, sección 9.20 y siguientes.

Tasas

Usa «por» en vez de la barra de división (/) cuando el espacio lo permite. La barra está bien donde el espacio es poco, como en una tabla de celdas chicas. Abrevia «por» a p solo en abreviaturas consolidadas de unidades de tasa, como Gbps (gigabits por segundo) o MBps (megabytes por segundo).

Unidades decimales y binarias

Mide los bytes con el mismo sistema que usa la tecnología que documentas. No uses MB si quieres decir MiB, ni GB si quieres decir GiB. La siguiente tabla lista las unidades comunes:

Para abreviar términos de medida, ver Abreviaturas.

Más recursos

• Notación matemática
• Números

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