La extraña distancia entre los desarrolladores y la documentación oficial
“¿Es que no puedo entender la documentación porque no tengo suficiente habilidad?” He creído eso durante bastante tiempo.
1. “Solo yo no lo entendía”
Frameworks, librerías, REST API, servicios en la nube… Hoy en día la mayoría de ellos tienen documentación oficial bien hecha. El problema es… no logro entenderla.
Al principio pensé así.
“Ah… todavía me falta experiencia. Si estudio más, algún día podré leer esta documentación sin problemas…”
Así que me esfuerzo por leerla. Pero:
- No comprendo el principio
- No sé dónde termina la teoría y comienza el ejemplo práctico
- He leído el contenido, pero al intentar escribir código me quedo sin saber por dónde empezar
- ¿Por qué la documentación es tan extensa?
Ahora me considero un desarrollador que ya no se identifica con el término “principiante”. Sin embargo, al ver la documentación de una nueva librería, mi mente se llena de:
“Vaya… otra vez empezando…”
Ya sé que no es solo falta de habilidad.
2. La documentación suele escribirse desde la perspectiva del creador
La razón principal por la que la documentación es difícil es que la mayoría de las guías oficiales están escritas desde la estructura mental del creador.
- Esa persona ya
- Conoce la arquitectura interna
- Sabe por qué se tomó esa decisión de diseño
- Conoce las limitaciones
- Sabe dónde y cómo se llama cada función
- Por eso la documentación suele incluir:
- “Este método recibe estos parámetros”
- “Devuelve este tipo”
- “En este caso lanza una excepción”
- “Con esto puedes hacer esto…”
El problema es que no somos el creador del programa.
Lo que nos interesa suele ser:
- “¿Por dónde empiezo?”
- “Para resolver este problema, ¿qué parte de la documentación debo leer?”
- “¿En qué situaciones se necesita esta opción?”
- “¿Cuándo se llama realmente a esta línea de código?”
Pero la documentación dice:
“Esta opción utiliza la acción foo y la estrategia bar para ejecutar baz.”
…y a ese punto, lo que quieres es probar un ejemplo primero.
3. “Mi propia documentación también resulta difícil”
Lo curioso es que cuando escribo documentación para mi propia API o librería, también la redacto desde la perspectiva del creador.
- “Esta función hace esto…”
- “Este endpoint recibe estos argumentos…”
- “Devuelve este JSON…”
- “En caso de éxito/fallo la respuesta es…”
Y pienso:
“¿No es esta documentación bastante amigable?”
Pero la reacción de mis compañeros suele ser:
- “¿Puedes explicarlo oralmente una vez?”
- “Hay documentación, pero me parece más rápido preguntar.”
Lo más divertido es que a veces no reconozco mi propia documentación.
Si intento usar una API que creé hace tiempo y abro la documentación antigua:
“¿Eh… esto es lo que escribí? ¿Por qué lo explico de esta manera extraña…?”
Entonces me doy cuenta de que:
- Escribir documentación no garantiza que sea fácil de entender.
- No tienes mucho derecho a criticar la documentación oficial que no entiendes. 😅
4. Es normal que la documentación oficial no se entienda de inmediato
Cada proyecto tiene al menos una librería o paquete que se usa constantemente. Esas son las que guardas en una pestaña del navegador y revisas mientras trabajas.
Pero lo curioso es:
- Al principio: “¿Qué está diciendo esto?”
- Al final del proyecto: “Ah, ahora sí lo entiendo…”
Y a menudo pienso:
“¿No, esto estaba escrito aquí? Lo leí antes, pero no entendía su significado…”
¿Por qué sucede esto?
- Para comprender la documentación necesitas experiencia práctica y contexto.
- Y para ganar esa experiencia, primero debes leer la documentación y probar algo.
En otras palabras, necesitas estar entendiendo la documentación para poder entender la documentación. Es un círculo vicioso.
Así que ahora pienso:
“La documentación oficial no se entiende de una sola vez. Solo después de varios proyectos y revisiones se vuelve comprensible.”
Por eso es normal que al principio no se entienda. No es culpa tuya, es la naturaleza de la documentación.
5. Los desarrolladores no angloparlantes tienen una dificultad +2
Además, tenemos la desventaja de ser desarrolladores no angloparlantes.
- Podemos leer frases en inglés.
- Los términos técnicos ya los conocemos.
- Nos gusta leer libros y artículos, así que no sentimos falta de “comprensión lectora”.
Sin embargo, al leer documentación oficial, sentimos que nuestro cerebro se cansa más rápido.
Esto no se debe a falta de habilidad, sino a:
- El inglés en sí mismo consume “costo cognitivo”
- Y además
- Nuevos conceptos
- Diseños de API desconocidos
- Ejemplos de código abstractos llegan todos a la vez.
En otras palabras, estamos jugando un juego que consume más energía que los demás. Por eso nos sentimos más cansados y la tarea parece más difícil.
Cuando pienses: “¿Por qué me cuesta leer documentación oficial?” Puedes decirte a ti mismo:
“Ya estoy corriendo con una desventaja, pero sigo adelante.”
6. Pero… tenemos algunas habilidades de supervivencia
A continuación, comparto algunas técnicas de supervivencia documental que he aprendido.
6‑1. Dejar de intentar leer de principio a fin
La documentación oficial suele ser más un “referencia + diccionario” que un libro de introducción.
Por eso yo:
- Leo solo la sección “Getting Started / Quickstart / Tutorial”
- El resto lo uso como
- Búsqueda
- Referencia cuando surge un problema
6‑2. Entender primero con ejemplos, luego leer la explicación
- Escribo una línea de código
- Me lanza un error
- Busco el mensaje de error y vuelvo a la documentación
Entonces la frase cambia de:
- Al principio: “No entiendo lo que dice esto…”
- Después de varios intentos: “Ah, eso era el error que tuve antes…”
Cuando ya has fallado, la documentación se vuelve una historia que puedes seguir.
6‑3. Tomar notas en tu propio idioma
La documentación está en su propio idioma, así que suelo hacer anotaciones:
- “Si esta opción es true, básicamente es modo
XXX” - “Esta función es como una fábrica que crea X”
- “Recuerda memorizar esto. La comprensión profunda viene después.”
Cuando vuelvo a leer mi “documentación personal”, la oficial y la mía se complementan y me siento más seguro.
7. No es culpa tuya
Si llegaste hasta aquí, probablemente también hayas sentido el desánimo frente a la documentación oficial.
- Frases que no entiendes después de varias lecturas
- Secciones que recuerdas haber visto pero no recuerdas su contenido
- Sentir que solo después de resolver el problema comprendes la documentación
Recuerda:
- No eres el único.
- La mayoría de los desarrolladores experimentados también se pierden.
- Incluso los usuarios diarios de una librería suelen buscar en Stack Overflow o GitHub Issues más que en la documentación oficial.
La documentación oficial está diseñada para ser difícil. Y eso no es tu culpa.
Lo que hacemos es:
- Releer cuando no entendemos
- Escribir código cuando no lo entendemos
- Fallar y volver a la documentación
- Y, con el tiempo, descubrir que la frase “ah, ahora sí lo entiendo” aparece.
Eso es parte de ser desarrollador.
Así que, a quien se sienta frustrado hoy, le digo:
“No estás fallando. Simplemente estás avanzando a la velocidad normal de un desarrollador.”
Todos seguimos aturdidos frente a la documentación, abriendo decenas de pestañas, buscando la página que vimos ayer, y a pesar de todo, los proyectos siguen funcionando y seguimos aprendiendo una línea de código a la vez. 🙂
No hay comentarios.