Mejor tipografía para documentación que los ingenieros sí leen

Por qué la tipografía es un problema de SRE

La documentación forma parte del plano de control. No metafóricamente—literalmente. Tus respuestas a incidentes, runbooks operativos, planes de migración y el conocimiento tribal de “este servicio está raro” viven ahí. Si la tipografía es hostil, el sistema se vuelve hostil. Los ingenieros seguirán implementando cambios, rotando claves y reconstruyendo arreglos. Solo que lo harán de memoria. Así obtienes procedimientos ligeramente distintos, suposiciones divergentes y el tipo de fallos que no se reproducen.

La tipografía afecta tres métricas operativas que deberías cuidar:

• Tiempo de respuesta bajo estrés. Un documento que se puede ojear gana. Un documento que exige leer pierde.
• Tasa de error durante copiar/pegar. Código envuelto, guionización ambigua y glifos que se parecen son fuentes confiables de comandos erróneos.
• Seguridad al cambiar. Si los encabezados no son anclas estables y la longitud de línea provoca un caos de reflujo, los revisores se pierden cambios y la documentación se aleja de la realidad.

La tipografía no arreglará una topología de almacenamiento rota. Pero evitará que el runbook mienta por el formato.

Una cita que sigue vigente en el trabajo de operaciones: La esperanza no es una estrategia. — Vince Lombardi. No es una cita de un ingeniero de software, lo que la hace aún más útil. El diseño de tu documento no debería depender de la esperanza de que el lector “se dé cuenta”.

Datos interesantes (porque esto tiene una historia)

• Las normas tempranas de longitud de línea vinieron de restricciones de impresión. Periódicos y libros convergieron en medidas moderadas porque las líneas largas aumentan los errores al volver la vista (perder el lugar).
• Las convenciones de la máquina de escribir moldearon las expectativas monospace. Las fuentes de ancho fijo entrenaron generaciones para leer columnas alineadas—todavía relevantes para logs, tablas y salida de CLI.
• La guionización solía ser trabajo manual. Los compositores insertaban guiones discrecionales a mano; los algoritmos modernos lo hacen automáticamente, a veces mal, especialmente con términos técnicos.
• ASCII es por qué aún luchamos con caracteres parecidos. El problema “1/l/I” es antiguo; el riesgo cambió cuando esos caracteres empezaron a aparecer en secretos, tokens y nombres de host.
• Markdown heredó hábitos de la era del correo electrónico. Muchas convenciones de Markdown se optimizaron para la legibilidad en texto plano, no para un renderizado pulido—de ahí interacciones extrañas con el envolvimiento y las cercas de código.
• El soporte de hiphenation en CSS es irregular. La propiedad hyphens depende de diccionarios de idioma y del comportamiento del navegador; no es determinista entre clientes.
• Las anclas se convirtieron en herramientas operativas. Una vez que la documentación se navega por fragmentos de URL, el texto de los encabezados empezó a actuar como una API—cambiarlo rompe runbooks y tickets.
• La selección de fuente de código afecta la claridad de los glifos. Algunas fuentes hacen que {}, [] y () sean demasiado parecidos a tamaños pequeños—genial para estética, terrible para producción.

Broma #1: La tipografía es como el monitoreo: si solo la notas cuando está fuerte, ya estás en problemas.

Longitud de línea: el sumidero de tiempo silencioso

Si el texto de tu documento ocupa todo el ancho de un monitor de 34 pulgadas, has creado una prueba de resistencia de escaneo. Las líneas largas no son “más información”. Son más recorrido ocular. El recorrido ocular cuesta tiempo. Bajo presión, el tiempo se convierte en errores.

Qué hacer

• Apunta a 60–80 caracteres por línea para el texto en cuerpo. Si necesitas un número único: 72 es un buen valor por defecto.
• Usa un max-width medido en caracteres (ch) en lugar de píxeles. Los píxeles mienten entre fuentes y dispositivos; los caracteres se acercan más a la realidad de lectura.
• Permite que el código sea más ancho que la prosa pero no lo dejes envolver por defecto. El desplazamiento horizontal en bloques de código es menos malo que comandos envueltos que cambian de significado.

Modos de falla que realmente verás

• Errores al volver la vista: el lector pierde su lugar al pasar del final de una línea larga al inicio de la siguiente, especialmente en párrafos densos.
• Colapso de escaneo: los encabezados se vuelven menos efectivos porque la página se convierte en una pared; la estrategia del lector pasa a ser “Ctrl+F y rezar”.
• Ruido en los diffs: si tu editor envuelve a un ancho y el sitio lo hace a otro, ediciones menores reescriben párrafos enteros y los revisores dejan de confiar en los diffs.

CSS que se comporta como un adulto

Este es el tipo de CSS que pones en un sitio de documentación y no tocas de nuevo a menos que disfrutes de postmortems.

cr0x@server:~$ cat docs-typography.css
:root{
  --measure: 72ch;
  --body-font: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif;
  --mono-font: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
  --base-size: 16px;
  --line-height: 1.55;
}
main, article{
  max-width: var(--measure);
  margin: 0 auto;
  padding: 0 1rem;
  font-family: var(--body-font);
  font-size: var(--base-size);
  line-height: var(--line-height);
}
pre, code, kbd, samp{
  font-family: var(--mono-font);
}
pre{
  overflow-x: auto;
  white-space: pre;
  tab-size: 2;
}
code{
  font-size: 0.95em;
}

Ese output es un archivo, no una promesa. La decisión que tomas: mide la prosa por caracteres, constrínela de forma centralizada y permite que los bloques de código desplacen horizontalmente en lugar de envolver.

No te pongas creativo con tipografía fluida sin salvaguardas

La tipografía fluida puede ser genial. También puede convertir silenciosamente una medida de 72ch en 110ch en pantallas anchas cuando se combina con un tamaño de fuente fluido. Si optas por fluido, limita la medida.

Encabezados que justifican su existencia

Los encabezados no son decoración. Son un sistema de navegación, un esquema para el escaneo y una API de anclas para enlazar desde tickets, alertas y chat. Cuando renombras encabezados a la ligera, rompes la memoria muscular de la gente. Cuando das formato pobre a los encabezados, haces la página inescaneable.

Reglas que te evitan problemas

• Una página, un H1. Haz que sea la promesa de la página. Si el título es vago, el resto no lo salvará.
• Las secciones H2 deben ser significativas sin contexto. “Configuración” no es una sección. “Configurar TLS para webhooks salientes” sí lo es.
• Mantén la jerarquía de encabezados poco profunda. H2 y H3 hacen la mayor parte del trabajo. H4 es un olor. H5 es un grito de ayuda.
• No estilices los encabezados tan agresivamente que parezcan anuncios. Alto contraste y peso razonable ganan; texto gigante con degradado pierde.
• Proporciona IDs estables a los encabezados. Si tu plataforma genera IDs automáticamente a partir del texto, cambiar una sola palabra rompe enlaces. Prefiere IDs explícitos o un mecanismo de alias.

Elecciones tipográficas que cambian el comportamiento

Los ingenieros hojean por forma. Si cada encabezado tiene el mismo peso que el texto del cuerpo, la página se aplana. Si cada encabezado es enorme, la página se vuelve ruidosa. Quieres una escalera tipográfica clara: H2 es visiblemente diferente, H3 es un subpaso y el texto del cuerpo se mantiene tranquilo.

El espaciado importa más que la fuente. La mejor fuente para encabezados del mundo no compensa un ritmo vertical apretado. Dale espacio a los encabezados arriba, un espacio más ajustado debajo y mantén las listas cerca del encabezado al que pertenecen.

Anclas como interfaces operativas

Si tu runbook de incidentes dice “Ir a ‘Procedimiento de reversión rápida’”, esa frase debe existir y debe ser enlazable. Trata las anclas de encabezado como endpoints de API: estables, versionadas si es necesario y no reescritas durante un “refresh de contenido”.

Fuentes de código y bloques de código: dejar de romper comandos

La documentación falla más en el código. La gente copia comandos, los pega en una shell root y pulsa Enter con la misma confianza que usa para aprobar una solicitud de cambio. Tu trabajo es evitar que el texto se mute entre pantalla y terminal.

Elige una fuente monospace por claridad, no por estilo

Las fuentes monoespaciadas son infraestructura. Escoge una con:

• Distinciones claras de glifos: O vs 0, l vs 1, {} vs (), y ; que no desaparezca.
• Buen hinting a tamaños pequeños para que el código no se vuelva borroso en pantallas de baja calidad.
• Ancho consistente para que tablas y salidas alineadas se mantengan alineadas.

Código inline vs bloques de código

• Código inline es para identificadores y fragmentos cortos: rutas de archivo, flags, claves JSON. Mantenlo corto; no pongas comandos completos inline.
• Bloques de código son para todo lo que esperas que la gente copie/pegue, cualquier cosa multilínea y cualquier cosa donde el envolvimiento cambie el significado.

Nunca envuelvas comandos por defecto

El código envuelto es una fábrica que produce comandos rotos sin error visible hasta que es demasiado tarde. Es especialmente desagradable con:

• cabeceras largas de curl
• kubectl expresiones JSONPath
• salida de CLI de almacenamiento donde las columnas transmiten semántica
• cualquier cosa con backslashes, comillas o heredocs

Haz confiable el copiar/pegar

Usa white-space: pre y desplazamiento horizontal. Si quieres ayudar a usuarios móviles, proporciona una versión corta del comando, no un ajuste suave. Además, asegúrate de que tu sitio no reemplace espacios normales por espacios sin separación o “mejoras tipográficas” dentro de los bloques de código. Así es como aparecen Unicode invisibles que rompen shells.

Broma #2: Lo único peor que un comando envuelto es un comando envuelto que todavía parece sin envolver.

Guiones: donde el buen diseño se encuentra con el mal copiar/pegar

La hipenación existe para que el texto justificado se vea menos con huecos. La mayoría de la documentación técnica no debería usar texto totalmente justificado. Si lo haces, estás invitando a problemas de hipenación, ríos de espacio en blanco y una página que parece un procesador de textos mal configurado.

Cuándo la hipenación ayuda

Para columnas estrechas (móvil, barras laterales), la hipenación puede reducir espacios extraños y evitar que el texto con margen irregular a la derecha parezca desordenado. Pero los docs técnicos no son novelas. Contienen identificadores que no deben dividirse con guiones: nombres de función, hostnames, flags y términos compuestos que deben permanecer buscables.

Reglas prácticas

• Desactiva la hipenación en código y cadenas de UI. Todo lo que un lector pueda copiar, teclear o buscar no debe hipenarse.
• Activa la hipenación solo para prosa y solo si la has probado en navegadores y el idioma del contenido está correctamente configurado.
• Evita texto justificado en el cuerpo. El margen irregular a la derecha está bien; tus lectores son ingenieros, no tipógrafos.

Enfoque CSS que no sabotea tokens

cr0x@server:~$ cat hyphenation.css
article{
  hyphens: auto;
}
code, pre, kbd, samp, a, .no-hyphen{
  hyphens: none;
}
h1, h2, h3{
  hyphens: manual;
}

Decisión: permite que el navegador hipene los párrafos (si realmente lo deseas), pero apágalo explícitamente para código, enlaces y todo lo que parezca un token. Además: establece correctamente el idioma del documento. Los diccionarios de hipenación dependen de ello.

Los guiones suaves son una trampa en documentación de ingeniería

Un guion suave puede colarse en texto copiado y arruinar coincidentes—especialmente en cuadros de búsqueda, valores YAML y cadenas de shell. La mayoría de los navegadores modernos no incluyen guiones suaves al copiar, pero “la mayoría” no es un contrato. Si necesitas control de salto de línea, usa CSS. Mantén el texto fuente limpio.

Guía rápida de diagnóstico

Esta es la guía “se siente ilegible”. Úsala cuando alguien se queje de que los docs son difíciles de leer, difíciles de ojear o “el comando que copié no funcionó”, y necesitas encontrar el cuello de botella rápido.

Primero: comprueba la medida y el envolvimiento (las mayores ganancias)

1. ¿La prosa está limitada a ~60–80 caracteres? Si no, arregla el max-width (prefiere ch).
2. ¿Se envuelven los bloques de código? Si es así, deténlo. Usa desplazamiento horizontal y white-space: pre.
3. ¿Son los encabezados visualmente distintos? Si los encabezados no destacan, el escaneo falla. Ajusta peso/tamaño/espaciado.

Segundo: comprueba la integridad del copiar/pegar

1. ¿Se aplican “comillas inteligentes” o sustituciones tipográficas al código? Romperán shells y JSON.
2. ¿Hay caracteres invisibles? NBSP, espacios de ancho cero, guiones suaves.
3. ¿Las fuentes hacen glifos ambiguos? Si O y 0 se ven idénticos, secretos e IDs se vuelven una ruleta.

Tercero: comprueba la navegación y las anclas

1. ¿El TOC refleja la estructura real? Si se genera automáticamente pero la jerarquía es caótica, no ayudará.
2. ¿Son estables las anclas de encabezado? Si la gente enlaza secciones desde tickets, cambiar IDs rompe el flujo operativo.
3. ¿Hay una búsqueda en la página que funcione? Si existe búsqueda pero la tipografía hace los encabezados poco descriptivos, los resultados son inútiles.

Doce+ tareas reales con comandos, salidas y decisiones

Estas son comprobaciones prácticas que puedes ejecutar en un repositorio de docs o en un sitio renderizado. Cada tarea incluye: un comando, salida realista, qué significa la salida y la decisión que tomas. Así conviertes “la doc se siente mal” en un ticket accionable.

Tarea 1: Buscar líneas sospechosamente largas en Markdown (prosa)

cr0x@server:~$ python3 - <<'PY'
import os, re
root="docs"
limit=120
hits=0
for dp, _, files in os.walk(root):
  for f in files:
    if not f.endswith(".md"): 
      continue
    p=os.path.join(dp,f)
    with open(p,"r",encoding="utf-8") as fh:
      for i,line in enumerate(fh,1):
        if len(line.rstrip("\n"))>limit and not line.lstrip().startswith(("```","    ")):
          hits+=1
          print(f"{p}:{i}:{len(line.rstrip())}")
print("hits",hits)
PY
docs/runbooks/restore.md:44:168
docs/guide/architecture.md:112:203
hits 2

Significado: dos líneas de prosa superan los 120 caracteres (no en bloques de código). Eso suele indicar párrafos sin reflujo o contenido pegado que se renderizará como líneas anchas.

Decisión: reestructurar esos párrafos en la fuente (o asegurar que el renderizador los envuelva). Si tu renderizador trata los saltos de línea en Markdown como saltos duros, debes refluírlos.

Tarea 2: Detectar bloques de código envueltos por CSS

cr0x@server:~$ rg -n "white-space:\s*pre-wrap|white-space:\s*normal" site/assets/*.css
site/assets/main.css:418:white-space: pre-wrap;

Significado: los bloques de código podrían estar usando pre-wrap que envuelve comandos largos.

Decisión: cambiar a white-space: pre para elementos pre y permitir desplazamiento horizontal.

Tarea 3: Verificar CSS computado para un bloque de código (sitio renderizado)

cr0x@server:~$ node - <<'NODE'
const fs=require('fs');
const html=fs.readFileSync('public/index.html','utf8');
console.log(html.includes('white-space: pre-wrap') ? 'pre-wrap found' : 'no pre-wrap in HTML');
NODE
no pre-wrap in HTML

Significado: el problemático pre-wrap probablemente proviene de una hoja de estilo externa, no del HTML inline.

Decisión: arreglar el CSS en la fuente (design system/tema), no en páginas individuales.

Tarea 4: Encontrar comillas inteligentes dentro de cercas de código

cr0x@server:~$ python3 - <<'PY'
import re, pathlib
root=pathlib.Path("docs")
bad = ["\u2018","\u2019","\u201c","\u201d"]
for p in root.rglob("*.md"):
  t=p.read_text(encoding="utf-8",errors="ignore")
  in_code=False
  for i,line in enumerate(t.splitlines(),1):
    if line.strip().startswith("```"):
      in_code = not in_code
    if in_code and any(ch in line for ch in bad):
      print(f"{p}:{i}: smart quote in code fence")
PY
docs/runbooks/backup.md:87: smart quote in code fence

Significado: hay comillas curvas dentro de un bloque de código, lo que puede romper shells y JSON.

Decisión: reemplazar por comillas ASCII y evitar que el editor/formatter “mejore” tipográficamente las cercas de código.

Tarea 5: Detectar espacios sin separación en bloques de código (asesinos de copiar/pegar)

cr0x@server:~$ python3 - <<'PY'
import pathlib
nbsp="\u00a0"
root=pathlib.Path("docs")
for p in root.rglob("*.md"):
  t=p.read_text(encoding="utf-8",errors="ignore")
  if nbsp in t:
    print(p, "contains NBSP")
PY
docs/guide/kubernetes.md contains NBSP

Significado: existe NBSP en algún lugar del Markdown. En código, puede romper flags y alineación de manera invisible.

Decisión: reemplazar NBSP por espacios normales; agregar una comprobación de linter para prevenir recurrencia.

Tarea 6: Auditar la jerarquía de encabezados (demasiado profunda, rara)

cr0x@server:~$ python3 - <<'PY'
import pathlib, re
root=pathlib.Path("docs")
for p in root.rglob("*.md"):
  levels=[]
  for line in p.read_text(encoding="utf-8",errors="ignore").splitlines():
    m=re.match(r'^(#{1,6})\s+', line)
    if m:
      levels.append(len(m.group(1)))
  if any(l>3 for l in levels):
    print(p, "has heading level > 3:", sorted(set(levels)))
PY
docs/guide/storage.md has heading level > 3: [1, 2, 3, 4, 5]

Significado: ese archivo usa H4/H5; probablemente está anidando detalles para compensar una mala estructura.

Decisión: reestructurar en menos secciones H2/H3 más significativas. La profundidad rara vez es claridad.

Tarea 7: Detectar IDs de ancla auto-generados inestables (riesgo para runbooks)

cr0x@server:~$ rg -n "##\s+.*\s+\(deprecated\)|##\s+.*\s+\(old\)" docs/runbooks
docs/runbooks/restore.md:12:## Restore Procedure (old)

Significado: los encabezados se están renombrando con calificadores como “(old)”, lo que probablemente cambia los slugs y rompe enlaces entrantes.

Decisión: mantiene el encabezado estable y marca el estado en otro lugar (badge, bloque de nota), o añade IDs explícitos si tu sistema lo permite.

Tarea 8: Confirmar que el desbordamiento de bloques de código está habilitado (evita el envolvimiento)

cr0x@server:~$ rg -n "pre\s*\{|pre\." site/assets/main.css | head
212:pre{
218:  overflow-x: auto;
219:  white-space: pre;

Significado: el CSS ya usa desplazamiento horizontal y preserva espacios en blanco.

Decisión: bien—déjalo así. Si los usuarios siguen reportando envolvimiento, busca CSS más específico que lo sobreescriba.

Tarea 9: Medir longitud media de línea en HTML renderizado (detectar diseños “a todo ancho”)

cr0x@server:~$ python3 - <<'PY'
from bs4 import BeautifulSoup
import pathlib, statistics, re
p=pathlib.Path("public/index.html")
soup=BeautifulSoup(p.read_text(encoding="utf-8",errors="ignore"),"html.parser")
text=" ".join(soup.get_text(" ").split())
chunks=re.findall(r'.{1,200}', text)
lens=[len(c) for c in chunks if len(c)>50]
print("sample chunk lengths:", lens[:8])
print("median:", int(statistics.median(lens)))
PY
sample chunk lengths: [200, 200, 200, 200, 200, 200, 200, 200]
median: 200

Significado: el texto extraído se fragmenta en 200 caracteres, así que esta muestra no es una medida perfecta—pero indica que la página tiene texto largo sin pausas naturales.

Decisión: usa esto como señal, no como prueba. El siguiente paso es la inspección visual y comprobar el max-width del contenedor en CSS.

Tarea 10: Encontrar configuraciones de hipenación en CSS (y dónde se aplican)

cr0x@server:~$ rg -n "\bhyphens\s*:" site/assets/*.css
site/assets/main.css:88:  hyphens: auto;
site/assets/main.css:97:  hyphens: auto;

Significado: la hipenación está habilitada en algún lugar, posiblemente de forma amplia.

Decisión: verifica que esté limitada a contenedores de prosa; desactívala para código, enlaces y spans tipo token.

Tarea 11: Detectar guiones suaves en el contenido fuente

cr0x@server:~$ python3 - <<'PY'
import pathlib
shy="\u00ad"
root=pathlib.Path("docs")
count=0
for p in root.rglob("*.md"):
  t=p.read_text(encoding="utf-8",errors="ignore")
  if shy in t:
    n=t.count(shy)
    count+=n
    print(p, "soft hyphens:", n)
print("total",count)
PY
total 0

Significado: no hay guiones suaves en Markdown. Bien—tu contenido no está ya intoxicado.

Decisión: mantenlo así evitando copiar/pegar desde fuentes que inyectan guiones suaves (algunos PDFs, algunos editores CMS).

Tarea 12: Verificar que el idioma del documento esté establecido (hipenación y lectores de pantalla)

cr0x@server:~$ python3 - <<'PY'
import pathlib, re
html=pathlib.Path("public/index.html").read_text(encoding="utf-8",errors="ignore")
m=re.search(r'<html[^>]*\blang="([^"]+)"', html)
print("lang=", m.group(1) if m else "missing")
PY
lang= en

Significado: el idioma está establecido. Eso afecta los diccionarios de hipenación y las herramientas de accesibilidad.

Decisión: asegúrate de que cada página establezca lang, no solo la plantilla de la página principal.

Tarea 13: Buscar bloques de código sin etiquetas de lenguaje (deteriora legibilidad y seguridad al copiar)

cr0x@server:~$ python3 - <<'PY'
import pathlib, re
root=pathlib.Path("docs")
for p in root.rglob("*.md"):
  lines=p.read_text(encoding="utf-8",errors="ignore").splitlines()
  for i,l in enumerate(lines,1):
    if l.strip()=="```":
      print(f"{p}:{i}: code fence without language")
      break
PY
docs/guide/ssl.md:55: code fence without language

Significado: las cercas sin etiqueta reducen la calidad del resaltado de sintaxis y a veces afectan widgets de copia o reglas de estilo.

Decisión: etiqueta las cercas (bash, json, yaml). La consistencia ayuda a lectores y herramientas.

Tarea 14: Comprobar tabs en bloques de código (la alineación se rompe según el entorno)

cr0x@server:~$ python3 - <<'PY'
import pathlib
root=pathlib.Path("docs")
in_code=False
for p in root.rglob("*.md"):
  in_code=False
  for i,line in enumerate(p.read_text(encoding="utf-8",errors="ignore").splitlines(),1):
    if line.strip().startswith("```"):
      in_code=not in_code
    if in_code and "\t" in line:
      print(f"{p}:{i}: tab in code fence")
      break
PY
docs/runbooks/network.md:102: tab in code fence

Significado: tabs dentro de cercas de código pueden renderizarse de forma inconsistente; la salida dependiente de alineación o YAML es especialmente frágil.

Decisión: convertir tabs a espacios; establece tab-size en CSS si debes conservarlos (pero no lo hagas).

Mini-historias corporativas (porque así es como falla)

1) Incidente causado por una suposición equivocada: “El sitio de docs envuelve código de forma segura”

La empresa tenía un portal interno de docs con buen aspecto. Tema bonito, buena búsqueda, todo el pitch de “experiencia de desarrollador”. Los runbooks eran Markdown, renderizados por un generador de sitios estáticos con una capa CSS corporativa encima.

Durante una rotación rutinaria de certificados, un ingeniero junior de guardia siguió el runbook y copió un largo comando openssl con múltiples flags y rutas de archivo. El bloque de código se veía bien visualmente, porque el tema envolvía suavemente líneas largas e insertaba una sutil sangría en el salto. En el terminal, el comando pegado incluyó un salto de línea a mitad de un flag. El comando falló, y el ingeniero—bajo estrés leve—hizo el movimiento clásico: lo editó hasta que funcionó.

Funcionó. También generó una clave con parámetros distintos a los previstos y la dejó en un directorio diferente al que el servicio esperaba. El despliegue posterior recogió el archivo equivocado y un subconjunto de instancias empezó a fallar en los apretones TLS. El incidente no derribó todo el servicio. Simplemente hizo que una porción del tráfico fallara de forma intermitente, lo cual es peor porque parece un gremlin de red.

El postmortem no fue sobre el ingeniero. La suposición equivocada fue estructural: “Si el comando está en un bloque de código, es seguro copiarlo.” No lo era. La solución fue aburrida: deshabilitar el envolvimiento en bloques de código, añadir un botón de copia que copie el texto crudo y lint para runbooks con comandos de línea única demasiado largos. También añadieron una sección explícita de “Salida esperada” en el runbook para que el ingeniero detectara divergencias antes.

2) Optimización que salió mal: “Habilitemos justificación completa y hipenación para una sensación ‘de libro’”

Una iniciativa de rediseño de docs decidió que la plataforma interna se veía “demasiado wiki”. Alguien quiso que pareciera una base de conocimiento pulida. Habilitaron texto justificado para crear bordes limpios izquierdo y derecho, luego activaron hipenación automática para reducir grandes huecos entre palabras.

En escritorio, la página de inicio se veía… bien. En móvil y pantallas divididas estrechas (modo común durante incidentes), la prosa se hipenó agresivamente. Eso habría sido solo molesto, salvo porque las reglas de hipenación a veces se activaban en términos técnicos compuestos en encabezados y en tokens embebidos en la prosa. Los lectores empezaron a buscar términos que habían visto en la página y no podían encontrarlos porque recordaban fragmentos hipenados.

El problema mayor afectó runbooks: los respondedores de incidentes hojean los encabezados para navegar. Los encabezados hipenados rompieron ese patrón de escaneo. La gente dejó de usar el TOC porque los saltos de línea hacían que los títulos de sección parecieran palabras distintas. Y como el equipo usaba anclas auto-generadas, pequeñas ediciones al texto del encabezado cambiaban los IDs, así que los enlaces de tickets antiguos se rompían. “La doc está mintiendo” se convirtió en una queja común.

El rollback fue directo pero políticamente doloroso: prosa con margen irregular a la derecha, hipenación desactivada por defecto, hipenación permitida solo en párrafos largos en pantallas estrechas y nunca en encabezados ni en nada marcado como código. El equipo de rediseño aprendió una verdad práctica: la tipografía que optimiza por estética puede reducir la precisión operativa. La meta no es “como un libro”. La meta es “correcto bajo estrés”.

3) Práctica aburrida pero correcta que salvó el día: anclas estables y tipografía conservadora

En otro lugar, el equipo de docs tenía una costumbre que parecía excesivamente cautelosa: trataban los encabezados y anclas como interfaces versionadas. Si un encabezado necesitaba renombrarse para mayor claridad, mantenían el ancla antigua como alias o dejaban el encabezado viejo como destino de ancla oculto. Los ingenieros bromeaban que la documentación estaba aplicando “gobernanza de API”. No estaban equivocados.

Entonces un incidente ocurrió durante una gran migración de plataforma. La mitad de la empresa estaba en una sala de guerra. Varios equipos estaban enlazando secciones del runbook en hilos de chat: “ir a la sección ‘Fallo de emergencia’”, “usar la lista ‘Deshabilitar escrituras’”, “verificar los pasos de ‘Salud del pool de almacenamiento’”. Esos enlaces tenían meses de antigüedad, sacados de tickets antiguos y de memoria muscular.

Funcionaron todos. No hubo 404s, ni “sección no encontrada”, ni cinco minutos perdidos por persona buscando el encabezado renombrado. La tipografía del sitio también era conservadora: medida legible, contraste fuerte en encabezados, bloques de código que no se envolvían y un diseño predecible donde los bloques de “Comando peligroso” parecían peligrosos.

Nada de ese diseño ganó premios. Hizo algo más valioso: redujo la sobrecarga de coordinación durante un outage. La gente pudo confiar en la forma del documento. Cuando la forma del documento es estable, los equipos gastan su presupuesto limitado de estrés en el sistema, no en la página.

Errores comunes: síntomas → causa raíz → solución

Esto es lo que aparece como “los docs son malos” en los formularios de retroalimentación. Los síntomas son reales. Las soluciones usualmente no son difíciles. Solo requieren que alguien trate la documentación como producción.

1) Síntoma: “Copié el comando y no funcionó”

Causa raíz: los bloques de código se envuelven, o la tipografía inteligente cambió comillas/guiones, o existen caracteres invisibles (NBSP, espacio de ancho cero).

Solución: imponer white-space: pre y overflow-x: auto; desactivar sustituciones tipográficas en código; añadir comprobaciones de linter para NBSP y comillas inteligentes en cercas de código.

2) Síntoma: “Esta página es agotadora de leer”

Causa raíz: longitud de línea demasiado larga; interlineado insuficiente; bajo contraste; párrafos densos sin estructura.

Solución: limitar la medida a ~72ch; establecer line-height ~1.5; aumentar ligeramente el espaciado entre párrafos; dividir secciones largas con encabezados H2/H3 significativos.

3) Síntoma: “El TOC es inútil”

Causa raíz: encabezados genéricos (“Overview”, “Details”), o jerarquía demasiado profunda/errática.

Solución: renombrar encabezados a enunciados orientados a la tarea; mantener la mayoría del contenido en H2/H3; colapsar o dividir páginas que requieren H4/H5.

4) Síntoma: “Los resultados de búsqueda no ayudan”

Causa raíz: los encabezados no contienen las palabras que buscan los usuarios; términos críticos están enterrados en prosa; la hipenación/saltos suaves afectan términos recordados.

Solución: escribe encabezados que coincidan con la intención del usuario; incluye términos clave temprano; evita hipenación de tokens; asegura que el indexado trate correctamente código y encabezados.

5) Síntoma: “Los enlaces en tickets antiguos van al lugar equivocado”

Causa raíz: los IDs de ancla auto-generados cambiaron cuando se editaron encabezados; el contenido se reorganizó sin redirecciones/alias.

Solución: usa IDs explícitos y estables; añade alias de ancla; trata los renombres como cambios de API con soporte de migración.

6) Síntoma: “Las tablas y la salida de CLI no se alinean”

Causa raíz: la fuente de código no es realmente monospace, o se usan fuentes proporcionales dentro de pre; las tabs se renderizan de forma inconsistente.

Solución: establece una pila monospace fiable para pre/code; convierte tabs a espacios; establece tab-size explícitamente.

7) Síntoma: “Los encabezados se sienten como oraciones en negrita al azar”

Causa raíz: contraste tipográfico insuficiente; espaciado de encabezados demasiado apretado; peso del encabezado demasiado ligero; estilos en mayúsculas reducen el reconocimiento de forma.

Solución: aumenta la diferencia de tamaño/peso; añade ritmo vertical; evita mayúsculas para encabezados largos; asegúrate de que los encabezados sean escaneables.

8) Síntoma: “El diseño móvil es un caos”

Causa raíz: los bloques de código intentan ajustarse a la pantalla envolviéndose; palabras largas desbordan; hipenación en encabezados.

Solución: permite que el código se desplace horizontalmente; añade overflow-wrap: anywhere solo para la prosa; mantén la hipenación desactivada para encabezados y código.

Listas de verificación / plan paso a paso

Lista de verificación: valores tipográficos por defecto para una plataforma de docs

• Contenedor de prosa max-width: 65–75ch.
• Tamaño de fuente del cuerpo: 16–18px según la fuente; line-height: 1.5–1.7.
• Texto con margen irregular a la derecha; evita la justificación completa.
• Escalera de encabezados: H2 claramente más fuerte que el cuerpo; H3 distinto pero no estridente.
• Bloques de código: white-space: pre, overflow-x: auto, botón de copia que copie texto crudo.
• Fuente de código: una pila monospace clara; evita ligaduras elegantes en docs operativos.
• Hipenación: desactivada globalmente a menos que hayas probado; si se habilita, limitarla a prosa.
• Anclas estables: IDs explícitos o estrategia de alias; trata los cambios de encabezado como cambios rompientes.
• Linter: detectar NBSP, comillas inteligentes en código, cercas sin lenguaje, tabs en YAML/código.

Plan paso a paso: arreglar un sitio de docs desordenado en una semana

1. Día 1: medir y evitar envolvimiento. Añadir max-width: 72ch al contenedor principal. Arreglar bloques de código para que no se envuelvan.
2. Día 2: encabezados y TOC. Normalizar la jerarquía de encabezados. Dividir páginas que requieren H4/H5 en páginas o secciones separadas.
3. Día 3: integridad del código. Desactivar tipografía inteligente en código. Añadir comprobaciones de linter para NBSP/comillas inteligentes. Añadir un botón “copiar crudo” si la plataforma lo soporta.
4. Día 4: estabilidad de anclas. Deja de confiar en IDs auto-generados si puedes. Añade alias para encabezados de runbook frecuentemente enlazados.
5. Día 5: decisiones sobre hipenación. O desactívala o limítala a prosa. Confirma que lang está establecido y es consistente.
6. Día 6: accesibilidad y contraste. Revisa el contraste de color para el texto y los encabezados. Haz visibles los estilos de foco para navegación por teclado.
7. Día 7: revisión operativa. Elige tres runbooks usados en incidentes reales. Simúlalos: copia/pega comandos, verifica salidas, comprueba si puedes ojear hasta la sección correcta en 10 segundos.

Cómo evitar regresiones

Las regresiones tipográficas son sigilosas porque nadie abre un ticket que diga “el interlineado bajó de 1.55 a 1.3”. Abren “los docs se sienten más difíciles”. Prevén eso con automatización:

• Revisión de CSS: cambios en pre, code, tamaños de encabezado y ancho de contenedor requieren aprobación.
• Lint de contenido en CI: rechazar NBSP y comillas inteligentes dentro de cercas de código.
• Pruebas de regresión visual en un puñado de páginas críticas (runbooks).

Preguntas frecuentes

1) ¿Cuál es la mejor longitud de línea para docs técnicos?

Para prosa, apunta a 60–80 caracteres por línea. Si necesitas un valor por defecto, usa 72ch en el contenedor principal. Es un punto medio para escaneo y reduce fatiga.

2) ¿Deben envolverse los bloques de código en móvil?

No. El envolvimiento cambia el significado y rompe copiar/pegar. Deja que los bloques de código se desplacen horizontalmente. Si un comando es demasiado largo para móvil, proporciona una alternativa corta o un archivo de script.

3) ¿La hipenación es buena o mala?

Mayormente mala en docs de ingeniería. Puede ayudar en columnas estrechas de prosa, pero debe estar desactivada para encabezados, código, enlaces y tokens. Si la activas, acótala y pruébala.

4) ¿Por qué no justificar el texto? Se ve más limpio.

El texto justificado suele producir espaciados irregulares (“ríos”) en la web, especialmente con columnas estrechas y términos técnicos mezclados. El margen irregular a la derecha es más legible y menos frágil.

5) ¿Cómo afectan los encabezados a la fiabilidad?

Los encabezados son APIs de navegación. Alimentan el TOC, la relevancia de la búsqueda y los enlaces entrantes desde tickets. Los encabezados malos ralentizan la respuesta a incidentes. Las anclas inestables rompen flujos operativos.

6) ¿Qué fuente monospace deberíamos usar?

Elige una pila monospace del sistema a menos que tengas una razón de peso para no hacerlo. Optimiza para claridad de glifos y renderizado a tamaños pequeños. Evita fuentes donde 0/O o 1/l/I sean ambiguos.

7) ¿Deberíamos usar ligaduras tipográficas en el código?

En docs operativos, recomiendo no. Las ligaduras pueden hacer que el código se vea bien pero confundir a los lectores y a veces afectar la selección/copia. Resérvalas para temas de editor, no para runbooks.

8) ¿Cómo prevenimos anclas rotas cuando cambian los encabezados?

Usa IDs explícitos cuando sea posible. Si tu plataforma genera anclas automáticamente, introduce un mecanismo de alias (anclas ocultas) para secciones comúnmente enlazadas. Trata los renombres de encabezados como cambios rompientes.

9) Nuestros docs están en Markdown. ¿Deberíamos forzar saltos de línea a 80 caracteres?

Depende del tooling. El hard-wrap puede mejorar diffs y revisiones, pero también puede crear saltos de línea extraños si tu renderizador los trata como saltos duros. Si los forzas, asegúrate de que tu procesador Markdown use la semántica normal de párrafos.

10) ¿Cuál es el cambio de mayor impacto único?

Dejar de envolver bloques de código y restringir la medida de la prosa. Esos dos cambios eliminan una cantidad sorprendente de fricción operativa.

Conclusión: próximos pasos que realmente mueven la aguja

La tipografía es una característica de fiabilidad. Determina si el documento es usable cuando el lector está cansado, interrumpido o tratando de no empeorar las cosas. Si quieres docs que los ingenieros realmente lean, no necesitas un rebranding. Necesitas unos cuantos valores por defecto tercos y algo de automatización.

Haz esto ahora

1. Configura tu contenedor principal a ~72ch de ancho máximo y un line-height sensato.
2. Haz que los bloques de código sean no envolventes con desplazamiento horizontal. Añade un botón de copia si puedes.
3. Desactiva la hipenación en encabezados, código, enlaces y spans tipo token. Considera desactivarla por completo.
4. Normaliza la jerarquía de encabezados: H2 útiles, H3 útiles, profundidad mínima.
5. Añade checks de lint en CI para comillas inteligentes, NBSP y cercas de código sin lenguaje.
6. Elige tres runbooks y simúlalos como si fuera un incidente. Si es molesto en calma, será peligroso a las 3 a.m.

Haz la página aburrida. Hazla consistente. Hazla segura para copiar. Así la documentación gana confianza, y la confianza es el recurso más raro en sistemas de producción.