Leer documentación técnica en inglés

La documentación oficial (documentation o docs) es la fuente más fiable para saber qué hace una función, qué le tienes que pasar y qué te devuelve. Casi siempre está en inglés y, aunque al principio abruma, tiene una estructura muy repetitiva. Si aprendes ese esqueleto y unas pocas palabras, puedes leer la documentación de cualquier lenguaje o librería sin traducirla entera. En esta lección verás cómo se organiza, qué significan sus secciones y los verbos y avisos que debes reconocer.

Los tipos de documentación

No todas las páginas sirven para lo mismo. Saber cuál buscas te ahorra mucho tiempo.

Inglés	Pronunciación	Qué es	Cuándo usarla
Getting started	/guéting stárted/	primeros pasos	Si acabas de descubrir la herramienta
Quick start	/cuik start/	inicio rápido	Para probarla en 5 minutos
Tutorial	/tiutórial/	tutorial guiado	Para aprender paso a paso
Guide	/gaid/	guía de un tema	Para entender un concepto
Reference / API reference	/réferens/, /ei pi ái/	referencia de cada función	Para consultar detalles exactos
FAQ	/ef ei kiu/	preguntas frecuentes	Para dudas típicas
Changelog	/chéindylog/	registro de cambios	Para ver qué cambia entre versiones
Migration guide	/maigréishon gaid/	guía de migración	Al actualizar a una versión nueva
Release notes	/rilís nóuts/	notas de versión	Para ver novedades
Troubleshooting	/trúbolshuting/	solución de problemas	Cuando algo falla

La reference es una enciclopedia: no se lee de principio a fin, se consulta. El tutorial sí se sigue en orden.

Anatomía de una página de referencia

Cuando buscas una función concreta, casi todas las páginas siguen el mismo patrón. Imagina esta documentación inventada de una función padStart (inspirada en la que existe en JavaScript):

padStart()

The padStart() method pads the current string with another string
until the resulting string reaches the given length. The padding
is applied from the start of the string.

Syntax
  padStart(targetLength)
  padStart(targetLength, padString)

Parameters
  targetLength
    The length of the resulting string once the current string has been padded.
  padString (optional)
    The string to pad with. Defaults to " ".

Return value
  A string of the specified length with padString applied from the start.

Examples
  "abc".padStart(5, "*");   // "**abc"

Esta es la estructura de casi cualquier página de referencia, y la traducción de cada parte:

Sección	Pronunciación	Qué contiene
Description / Summary	/diskrípshon/	Qué hace, en una o dos frases
Syntax	/síntaks/	Cómo se escribe la llamada
Parameters	/parámeters/	Qué le pasas (obligatorios y opcionales)
Return value	/ritérn válíu/	Qué te devuelve
Exceptions / Throws	/eksépshons/, /zrous/	Qué errores puede lanzar
Examples	/egsámpols/	Ejemplos de uso
Notes	/nouts/	Detalles adicionales
Browser compatibility	/bráuser compatibíliti/	En qué navegadores funciona
See also	/si ólso/	Funciones relacionadas
Specifications	/spesifikéishons/	Estándar oficial

Lee el ejemplo: “The padStart() method pads the current string with another string until the resulting string reaches the given length.” En español: “El método padStart() rellena el texto actual con otro texto hasta que el resultado alcance la longitud indicada.” La palabra pad (/pad/) significa “rellenar”.

Y esa llamada en la práctica:

console.log("abc".padStart(5, "*")); // **abc

Verbos y palabras típicas

La documentación usa un vocabulario muy concreto. Estos son los verbos que más verás.

Inglés	Pronunciación	Significado	Ejemplo
returns	/ritérns/	devuelve	“Returns a new array”
takes	/téiks/	recibe, toma	“Takes two arguments”
accepts	/aksépts/	acepta	“Accepts a callback function”
creates	/criéits/	crea	“Creates a new object”
modifies	/módifais/	modifica	“Modifies the original array”
throws	/zrous/	lanza	“Throws a TypeError”
defaults to	/difólts tu/	por defecto vale	“Defaults to 10”
specifies	/spésifais/	especifica	“Specifies the encoding”
represents	/reprisénts/	representa	“Represents a date”
must / should / may	/mast/, /shud/, /mei/	debe / debería / puede	ver abajo

Mira lo importante de returns a new array en JavaScript: algunos métodos devuelven un resultado nuevo y no cambian el original; otros modifican el original (mutate, /miuteit/, “mutar”). Esa diferencia está en la documentación y puede salvarte de errores:

const a = [3, 1, 2];
console.log(a.slice(1)); // [ 1, 2 ]  (returns a new array; a doesn't change)
console.log(a.sort());   // [ 1, 2, 3 ]  (sorts the array in place)
console.log(a);          // [ 1, 2, 3 ]  (a was modified)

Cuidado: sort modifica el array original (in place, /in pleis/, “en el sitio”). Si quieres conservar el original, haz antes una copia: [...a].sort().

Verbos modales: must, should, may, can

Los verbos modales indican si algo es obligatorio, recomendable u opcional. En documentación técnica significan algo muy preciso:

Inglés	Pronunciación	Fuerza	Ejemplo
must	/mast/	obligatorio	“The path must be absolute”
must not	/mast not/	prohibido	“The name must not be empty”
should	/shud/	recomendado	“You should close the file”
should not	/shud not/	desaconsejado	“You should not use this in production”
may / can	/mei/, /can/	permitido, opcional	“You may specify a timeout”
will	/uil/	ocurrirá	“The function will throw”
cannot	/cánot/	imposible	“You cannot change a constant”

Cuando una guía dice “You must…”, es obligatorio. Cuando dice “You should…”, es muy recomendable pero no impide que funcione. Y “You may…” es opcional.

Avisos y etiquetas

Las docs resaltan avisos con palabras en negrita o en recuadros de colores.

Etiqueta	Pronunciación	Significado
Note	/nout/	nota: información adicional
Tip	/tip/	consejo útil
Important	/impórtant/	importante
Warning	/uórnin/	aviso: puede causar problemas
Caution / Danger	/cóshon/, /déinyer/	cuidado: puede romper algo
Deprecated	/déprikeitid/	obsoleto: no lo uses en código nuevo
Experimental	/eksperiméntal/	experimental: puede cambiar
Legacy	/légasi/	heredado, de versiones antiguas
Removed	/rimúvd/	eliminado
Read-only	/rid óunli/	solo lectura
Since version 2.0	/sins/	desde la versión 2.0
Not supported	/not sapórted/	no soportado

Un ejemplo de aviso real que podrías encontrar:

Deprecated: This method has been deprecated since version 3.0
and will be removed in version 4.0. Use fetchAll() instead.

Traducción: “Obsoleto: este método está obsoleto desde la versión 3.0 y se eliminará en la versión 4.0. Usa fetchAll() en su lugar.” La estructura will be removed (se eliminará) es pasiva futura: muy común en changelogs.

Cómo orientarte sin entenderlo todo

La documentación no está pensada para leerse palabra por palabra. Estas estrategias te ayudan:

1. Empieza por el ejemplo. Salta a la sección Examples, lee el código y deduce qué hace. Luego vuelve a la descripción.
2. Lee la firma (Syntax) con calma. Los corchetes [ ] o la palabra optional indican que un parámetro se puede omitir.
3. Busca la palabra clave en la página con Ctrl + F: returns, throws, default.
4. Mira la versión. Comprueba que la documentación corresponde a tu versión (v18, 3.12…). Suele haber un selector arriba.
5. Traduce frases sueltas, no la página entera. Así aprendes los términos.
6. Pasa a la sección See also si no es lo que buscabas.

Un ejemplo completo en Python

La documentación de Python incluye la función sorted. Su firma real es esta, y debajo tienes un resumen en inglés sencillo escrito por nosotros, con el estilo habitual de una referencia:

sorted(iterable, /, *, key=None, reverse=False)
  Returns a new list with the items of the iterable, sorted.
  The original object is not changed.
  Use key to choose what to compare, and reverse=True for descending order.

Traducción: “Devuelve una lista nueva con los elementos del iterable, ordenados. El objeto original no cambia. Usa key para elegir qué comparar y reverse=True para el orden descendente.” Y funciona así:

print(sorted([3, 1, 2], reverse=True))  # [3, 2, 1]

Fíjate en los valores por defecto de la firma: key=None, reverse=False. Si no los das, valen eso. Y en iterable (/íterabol/): cualquier cosa que se pueda recorrer (lista, texto, tupla…).

Frases típicas para consultar

Mini-diccionario de frases que verás cuando busques ayuda:

Frase	Significado
“Learn more”	Saber más
“Read the docs”	Lee la documentación
“For more information, see…”	Para más información, mira…
“As of version X”	A partir de la versión X
“Backwards compatible”	Compatible con versiones anteriores
“Breaking change”	Cambio que rompe código existente
“Out of the box”	Funciona de serie, sin configurar
“Under the hood”	Por debajo, internamente
“Edge case”	Caso límite, poco habitual
“Best practice”	Buena práctica
“Pull request welcome”	Se aceptan aportaciones
“Open source”	Código abierto

Errores frecuentes

• Abrir primero un tutorial traducido de hace años. Las traducciones se quedan anticuadas; la documentación oficial se actualiza. Compara siempre con la versión actual.
• Leer la documentación como si fuera un libro. La referencia se consulta, no se lee entera. Salta al apartado que necesitas.
• Ignorar el Return value. Ahí está la clave para saber qué obtendrás y si modifica el original.
• No distinguir must de should. El primero es obligatorio; el segundo, recomendación.
• Fiarte de la primera respuesta de un foro sin mirar la doc. Puede ser de una versión anterior. Comprueba contra la referencia.
• Confundir argument con parameter. En la documentación, los parameters son los que define la función; los arguments los que tú pasas.

Resumen

Sección	Qué te dice
Description	Qué hace
Syntax	Cómo se escribe
Parameters	Qué le pasas, qué es obligatorio u optional
Return value	Qué devuelve
Throws / Exceptions	Qué errores lanza
Examples	Cómo se usa
See also	Cosas relacionadas
Deprecated / Experimental	Estado de la función
must / should / may	Obligatorio / recomendado / opcional

Ahora que sabes leer documentación, aprende a escribirla: Comentarios y README.