Enlaces

Esta sección cubre las referencias cruzadas: cuándo enlazar, a qué destino, con qué texto y con qué fórmula de introducción. También explica cómo convertir un encabezado en un destino de enlace estable con un atributo id, de modo que los enlaces entrantes sobrevivan a los cambios de redacción. Aplica a la documentación del grupo (el manual de operación, los README de cis-admin y cochid-datos, el archivo societario) y a las interfaces que escriben prosa.

Referencias cruzadas y enlaces

En general, una referencia cruzada enlaza información no esencial que complementa la comprensión del lector.

Bien usadas, las referencias cruzadas ayudan a navegar y a entender la documentación. Mal usadas, interrumpen. Las pautas de esta sección reducen la interrupción sin renunciar a las referencias que el lector necesita.

Elige los enlaces con criterio

Sé selectivo con los enlaces que incluyes en una página. Cada enlace es una decisión para el lector y suma carga cognitiva. Cada enlace es también una oportunidad de salir de la página y perder el hilo. Cuando incluyas un enlace, elige el destino más pertinente.

Da el contexto en la página

Cuando puedas, ayuda en contexto en vez de enlazar a otra parte. En estas situaciones, por ejemplo, considera dar la información en la página en lugar de enlazar:

• Definir un término.
• Explicar un concepto en pocas líneas.
• Dar un par de pasos.

Un caso concreto: si el lector necesita entender el software o los estándares de otro producto, conviene enlazar a documentación buena de afuera antes que documentar a fondo un estándar ajeno en la nuestra. Pero si al lector le bastan dos o tres oraciones de información básica, es mejor darle ese contexto y ahorrarle el viaje fuera de nuestra documentación.

Evita los enlaces duplicados

Por regla general, dentro de una misma página no repitas enlaces al mismo destino. Pon el enlace una vez, en el lugar donde más le sirve al lector.

Está bien agregar un segundo enlace en situaciones como estas:

• Enlazas a una sección distinta de la misma página de destino.
• Tu página es muy larga y los enlaces repetidos quedan lejos uno del otro.
• El documento tiene varios puntos de entrada. Por ejemplo, si una página tiene una sección de procedimiento y otra de solución de problemas, puede que necesites el mismo enlace en ambas.

Enlaza al destino más pertinente

Cuando enlaces, apunta a la página más pertinente del sitio y, dentro de ella, al encabezado más pertinente. Evita varios enlaces que hacen el mismo trabajo.

Enlaza a sitios de terceros

Nuestra documentación suele dar por sabido algo de estándares o software de terceros. En esos casos conviene enlazar antes que documentar a fondo un estándar ajeno. Pero, como con todo enlace, si puedes dar la información breve en la página, dala en la página. Para más información sobre qué reproducir y qué no, consulta Contenido de terceros.

Escribe texto de enlace descriptivo

Para el texto del enlace usa frases cortas, únicas y descriptivas que den contexto sobre el material enlazado.

Un buen texto de enlace mejora la accesibilidad y la lectura rápida. No todos los lectores viven los enlaces igual. Quien usa un lector de pantalla suele saltar de un enlace al siguiente sin leer lo que hay entre medio. Otros lectores recorren la página con la vista buscando el enlace que les sirve. Para más información, consulta Accesibilidad.

A veces hay que reescribir la oración para que contenga una frase que funcione como texto de enlace.

Dos opciones de texto de enlace eficaz

Como texto de enlace usa el título exacto de la página o una frase descriptiva, como se explica a continuación.

El título de la página como texto de enlace

Una opción es que el texto del enlace coincida con el título de la página o el encabezado al que remites. El título conserva su mayúscula inicial y el resto va en minúscula de oración, como todo título de la casa (P37). Para más información sobre cómo escribir un título dentro de una referencia, consulta Títulos y encabezados.

Una frase descriptiva como texto de enlace

La otra opción es describir la página de destino con una frase escrita como parte de la oración, en minúscula.

Cuando escribas una frase descriptiva como texto de enlace, ayuda al lector a decidir rápido si el enlace le sirve:

• Pon las palabras importantes al comienzo del texto del enlace.
• No uses el mismo texto de enlace para dos destinos distintos en el mismo documento.
• Mantén el texto corto cuando puedas. No enlaces una oración entera ni un párrafo.

Evita el texto de enlace vago

Escribe un texto de enlace que tenga sentido sin el texto que lo rodea. No uses frases como este documento, este artículo o haz clic aquí.

Evita las URL como texto de enlace

En general, no uses una URL como texto de enlace. Usa el título de la página o una descripción de la página.

Excepción: en algunos documentos legales (por ejemplo, términos de servicio o la política de privacidad) está bien usar la URL como texto de enlace.

Incluye la abreviatura en el texto del enlace

Si el texto trae una abreviatura entre paréntesis, incluye la forma larga y la abreviatura dentro del texto del enlace. Para más información sobre cómo introducir una sigla, consulta Abreviaturas.

Enlaza a comandos

Si el texto incluye un comando u otro elemento que va en fuente de código, incluye la descripción del elemento dentro del texto del enlace, salvo que quede forzado o redundante. Para más información sobre qué va en fuente de código, consulta Código en el texto.

Introduce el enlace con una fórmula fija («Para más información»)

Cuando dediques una oración aparte a una referencia cruzada, introdúcela siempre con la misma fórmula: «Para más información, consulta…» o «Para más información sobre…, consulta…».

Incluye la cláusula «sobre…» cuando el texto del enlace o el contexto no dejan claro por qué remites al lector a esa información. Para más información, consulta la sección Aclara el propósito del enlace de esta página.

La casa fija un solo término para cada cosa (P07):

• La preposición es sobre. No uses acerca de, respecto a, en relación con ni en torno a en esta fórmula.
• El verbo es consulta, en segunda persona de tú (P06). No uses vea, véase, mira, revisa ni chequea para remitir a un enlace o a una referencia cruzada. Para más información, consulta Términos de la casa.

Aclara el propósito del enlace

Asegúrate de que el contexto o el propio texto del enlace dejen claro por qué remites al lector a esa información. Sé específico en la explicación, pero no repitas el texto del enlace.

Si introduces la referencia con «Para más información…», basta con agregar la cláusula «sobre…». Para más información, consulta la sección Introduce el enlace con una fórmula fija de esta página.

Explica el comportamiento inesperado

Si un enlace lleva a un destino inesperado o se comporta de un modo inesperado, dilo. Algunas situaciones:

Enlaces que descargan archivos o abren el correo. Si un enlace descarga un archivo o abre un mensaje de correo, déjalo claro en el texto del enlace y menciona el tipo de archivo.

El dominio example.com está reservado para ejemplos. Para más información, consulta Dominios y nombres de ejemplo.

Enlaces a secciones de la misma página. Cuando enlaces a otra sección de la misma página, avisa al lector que el enlace lo lleva a otra parte de la misma página. Usa siempre la misma frase para señalarlo: «la sección … de esta página».

Enlaces a secciones de otra página. Cuando enlaces a un encabezado de otra página, usa la misma redacción y el mismo formato que en una referencia cruzada normal.

Si el título de la sección de destino es idéntico a un título de la página de origen, agrega contexto a la referencia.

Enlaces que abren en una pestaña nueva. Para más información, consulta la sección Abre los enlaces en la pestaña actual de esta página.

Enlaces que van a otro dominio o servidor. Para más información, consulta la sección No uses íconos de enlace externo de esta página.

Abre los enlaces en la pestaña actual

No fuerces los enlaces a abrirse en una pestaña o ventana nueva. Deja que el lector decida cómo abrirlos.

En el caso raro de que un enlace tenga que abrirse en una pestaña nueva, avisa al lector que el enlace se comporta distinto de lo esperado.

No uses íconos de enlace externo

No uses un ícono de enlace externo para indicar que el enlace va a otro dominio u otro servidor. Si te parece importante avisar que el lector sale de un dominio del grupo, dilo en el texto y no dependas de un ícono.

Puntuación alrededor del texto del enlace

Si hay un signo de puntuación justo antes o justo después de un enlace, déjalo fuera de las etiquetas del enlace siempre que puedas. En español esto incluye los signos de apertura: «¿» y «¡» quedan fuera igual que «?» y «!».

Comillas y cursivas

Cuando la referencia cruzada es un enlace, no pongas el texto del enlace entre comillas.

En el caso raro de que la referencia cruzada no sea un enlace, usa comillas o cursiva según corresponda. Las comillas de la casa son las angulares «», y las inglesas "" solo dentro de un texto ya entrecomillado. Para más información, consulta Comillas.

Para una referencia sin enlace a una sección de documento, una obra corta o una parte de una serie (un capítulo, un episodio), usa comillas angulares.

Para una referencia sin enlace al título de una obra completa (un libro, una película, una serie), usa cursiva.

Evita los enlaces externos en la navegación de la documentación

En la navegación de un conjunto de documentos (por ejemplo, una tabla de contenidos o un menú lateral como el de esta guía) no enlaces fuera del conjunto. Pon ese enlace en una página de la documentación.

Si de todos modos necesitas enlazar fuera del conjunto desde la navegación, deja claro al lector que va a salir de ese conjunto de documentos.

Estilo del texto de enlace

Si escribes la CSS de todo un sitio, aplica un estilo estándar al texto de enlace. Eso ayuda al lector a encontrar los enlaces en el contenido. En los sitios del grupo ese estilo ya viene en el kit: preflight.css pinta los enlaces con var(--c-blue) y los subraya. No lo sobrescribas con colores propios; si un sitio necesita otra cosa, el cambio va en los tokens del kit.

Contrasta el color del enlace con el del texto. Para que el lector vea los enlaces, el texto enlazado tiene que distinguirse del resto del texto de la página.

Subraya el texto de enlace y no subrayes el texto que no es enlace. Cuando el lector recorre la página, una línea horizontal corta la línea vertical del barrido y le ayuda a encontrar los enlaces.

Haz que los enlaces visitados cambien de color. Usa cambios de color aptos para daltónicos, de modo que el lector distinga los enlaces que ya siguió de los que no. Así navega el sitio sin volver a leer lo que ya leyó. Hoy el kit mantiene el mismo color para a:visited; si tu sitio necesita la distinción, pídela como cambio de token y no con un hexadecimal local.

Encabezados como destino de enlace

Esta sección explica cómo convertir un encabezado en un destino de enlace con un atributo id. Para más información sobre cómo redactar y formatear un encabezado, consulta Títulos y encabezados.

Algunos sistemas de gestión de contenidos y generadores de sitios (GitHub, MkDocs, Docusaurus) crean anclas automáticas para los encabezados. Aun así, conviene agregar un ancla propia en estos casos:

• Quieres un ancla más corta que la generada automáticamente.
• El contenido va a recibir muchos enlaces. Un ancla propia reduce la probabilidad de romper enlaces existentes si el texto del encabezado cambia después.
• Vas a revisar un encabezado. Si el ancla se genera automáticamente, cambia con la redacción del encabezado y rompe los enlaces existentes.

En español hay una razón más: cada generador trata distinto las tildes y la eñe. Uno conserva «ó» en el ancla, otro la translitera a «o» y otro la elimina, así que el mismo encabezado «Introducción a todo» produce tres anclas distintas según la herramienta. Por eso la casa escribe siempre el ancla a mano y en ASCII: minúsculas, sin tildes ni eñes, con guiones entre palabras (introduccion-a-todo, no introducción-a-todo). Los encabezados de esta guía usan anclas cortas y estables (t1, t2…) justamente para que el menú lateral no se rompa al retocar un título.

Agrega un ancla propia

HTML

Para agregar un ancla a un encabezado en HTML, envuelve el encabezado en un elemento section con atributo id, o pon el id directamente en la etiqueta del encabezado. Para el texto del ancla usa minúsculas, ASCII y guiones entre palabras. En los ejemplos, reemplaza ID_DEL_ANCLA por tu texto de ancla, por ejemplo introduccion-a-todo. Para más información sobre cómo se escriben los marcadores de posición, consulta Formato de marcadores de posición.

<section id="ID_DEL_ANCLA"></section>

La guía original de Google también recomienda un elemento a con atributo name, antes o dentro del encabezado. En el estándar HTML vigente el atributo name de a está obsoleto, así que la casa lo acepta solo en páginas heredadas y no en código nuevo. Para más información, consulta HTML y etiquetado semántico.

Markdown

Para agregar un ancla a un encabezado en Markdown, agrega este código al final de la línea del encabezado. La sintaxis es la de la extensión attr_list (MkDocs, Python-Markdown, kramdown). Para el texto del ancla usa minúsculas, ASCII y guiones entre palabras. En los ejemplos, reemplaza ID_DEL_ANCLA por tu texto de ancla, por ejemplo rotar-llave.

{: #ID_DEL_ANCLA }

El Markdown de GitHub no admite attr_list. En un README que se lee en GitHub, pon la línea <a id="rotar-llave"></a> justo antes del encabezado: GitHub conserva el HTML en línea y el ancla funciona igual. Para más información sobre cuándo escribir HTML dentro de Markdown, consulta Markdown contra HTML.

Revisa un encabezado

Si revisas un encabezado en un sistema que genera anclas automáticas, puedes crear un ancla propia para no romper los enlaces existentes. Si el encabezado ya tiene un ancla propia, no la cambies salvo que contenga un término que quieras eliminar (por ejemplo, un término irrespetuoso).

Para crear el ancla propia, usa la cadena del id antiguo del encabezado. Puedes encontrarla inspeccionando el encabezado en la página publicada. Por ejemplo, si cambias un encabezado de «Introducción a algunas cosas» a «Introducción a todo», agrega un ancla propia con la cadena y el formato del id antiguo.

HTML

Markdown

Si necesitas cambiar un ancla propia que ya existe, revisa en el sistema de gestión de contenidos (o con un grep sobre los repos del grupo) qué enlaces usan el ancla antigua y actualízalos. Los enlaces entrantes con el ancla antigua siguen llegando a la página, pero no a la sección ni al encabezado.

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