Leer documentación sin traducirla
Traducir mentalmente palabra por palabra es lento y además hace perder el hilo. La documentación técnica tiene una estructura fija que se puede recorrer salteando, y saber dónde está cada cosa importa más que entender cada oración.
La forma más común de leer documentación en inglés es la más lenta: empezar arriba, traducir cada oración, y llegar al final del primer párrafo sin acordarse qué se estaba buscando.
La documentación técnica no se lee como un texto: se recorre buscando algo. Tiene una estructura bastante fija, y cuando la conocés podés saltar directamente a la parte que responde tu pregunta, que suele ser una de cinco.
Dónde está cada cosa
| Sección | Cómo se llama | Qué responde | Cuándo ir ahí |
|---|---|---|---|
| Introducción | Overview, Introduction, About | Qué es y para qué sirve | La primera vez, y sólo esa vez |
| Arranque | Getting started, Quickstart | Cómo hacerlo andar en cinco minutos | Para empezar rápido |
| Guías | Guides, How-to, Tutorials | Cómo hacer una tarea concreta | Cuando sabés qué querés hacer |
| Referencia | API reference, Configuration | Qué parámetros hay y qué hace cada uno | Cuando ya estás escribiendo código |
| Conceptos | Concepts, Architecture, How it works | Por qué funciona así | Cuando algo se comporta raro |
| Cambios | Changelog, Release notes, Migration guide | Qué cambió y qué se rompe | Antes de actualizar una versión |
Las señales que hay que ver sí o sí
Hay unas pocas frases que cambian lo que vas a hacer, y conviene reconocerlas de un vistazo:
| Señal | Qué significa | Qué hacer |
|---|---|---|
| Breaking change | Algo que funcionaba deja de funcionar | Leerlo entero antes de actualizar |
| Deprecated | Todavía anda, va a desaparecer | Anotarlo; migrar antes de que lo saquen |
| Experimental / Beta | Puede cambiar sin aviso | No apoyarse en eso para algo crítico |
| Note / Warning / Caution | Un detalle que rompe si se ignora | Son las tres líneas más útiles de la página |
| Defaults to… | El valor que toma si no lo configurás | Verificar que ese valor sea el que querés |
| Required / Optional | Si hace falta pasarlo | Lo primero que se mira en la referencia |
| Not recommended for production | Anda en tu máquina, no en serio | Buscar la alternativa que sí lo es |
Antes de seguir, predecí
Leer un changelog en dos minutos
Es el documento que más se lee mal, porque se lee entero cuando hay que recorrerlo al revés:
El procedimiento
- Buscá primero «Breaking changes». Si no hay, la actualización probablemente sea segura.
- Mirá el salto de versión. En versionado semántico, el primer número que cambia avisa que algo se rompe; el segundo, que hay cosas nuevas; el tercero, que son arreglos.
- Buscá los nombres que usás. Ctrl+F con las funciones o los parámetros de tu código: el 95 % del changelog no te aplica.
- Leé «Deprecations». No rompe hoy y define tu trabajo de los próximos meses.
- Si saltás varias versiones, buscá la guía de migración. Existe justamente para eso y ahorra leer cinco changelogs.
Y del otro lado: escribir para que otro lea así
Reescribilo
Una nota de versión escrita como si nadie la fuera a recorrer buscando algo. Reescribila para alguien que la va a leer en dos minutos antes de actualizar.
## v3.0.0
We have made several improvements to the library. The export function now works differently and we also changed how dates are handled. There are also some bug fixes. Please review before updating.## v3.0.0 ### Breaking changes - `export()` now returns a Promise. Add `await` at every call site. - Dates are returned in UTC instead of local time. ### Fixes - Fixed crash when exporting an empty table.
Separa lo que rompe de lo que no, y dice exactamente qué hacer en cada caso. Quien actualiza sabe en diez segundos si le afecta.
## v3.0.0 **Breaking:** `export()` is now async and dates are returned in UTC. See the [migration guide](./migrating-to-v3.md) for the two changes you need to make. Fixes: empty tables no longer crash on export.
Versión más corta, con el detalle en una guía aparte. Sirve cuando los cambios necesitan más explicación que una línea.
Las dos versiones dicen lo mismo que el original. La diferencia es que se pueden recorrer sin leerlas.
Lo que preguntan sobre esto
Cierre
Autoevaluación
¿Lo entendiste?
Práctica