Cómo yo, una desarrolladora principiante, leo el tutorial que tú (desarrollador) escribiste para mí

• Un texto que retrata con humor la confusión y las barreras que enfrenta una principiante al leer tutoriales técnicos escritos por desarrolladores
• Los términos especializados y abreviaturas que los desarrolladores usan con frecuencia suenan para una principiante como un “idioma alienígena” completamente fuera de contexto
• Los pasos de instalación, rutas de archivos y comandos de terminal suelen ser demasiado complejos o estar omitidos, lo que dificulta entenderlos
• La autora señala que explicaciones que parecen obvias desde la perspectiva de un desarrollador se convierten, para una principiante, en obstáculos que requieren horas de búsqueda y prueba y error
• Este texto les recuerda a quienes escriben tutoriales que deben explicar de forma más amable y clara desde la perspectiva de quien recién empieza

---

Contexto del texto y planteamiento del problema

• La autora describe su experiencia, como principiante y no desarrolladora, al leer tutoriales escritos por desarrolladores
• Satiriza la situación en la que los términos técnicos y nombres de herramientas que aparecen en un tutorial no le dicen absolutamente nada a una persona principiante
• Ejemplo: usa nombres técnicos ficticios como Hoobijag, Snarfus y Shamrock portal para enfatizar que, desde los ojos de una principiante, todo se ve complicado

---

Traducción del texto original

“¡Hola! Soy desarrolladora. Mi experiencia relevante es esta: programo con Hoobijag y a veces también uso jabbernocks, y por supuesto hago ABCDE++++ (pero nunca ABCDE+/^+, eso sería absurdo, ¿no? ¡jaja!) y me gusta trabajar con Shoobababoo y de vez en cuando también lidio con kleptomitrons. Terminé haciendo código relacionado con Shoobaboo en Company[1], y eso me llevó a Snarfus. ¡Bueno, empecemos!

Sobre este tutorial

Empecé haciendo una cosa muy simple[2] con Snarfus por primera vez, pero mientras más lo usaba, más le veía el potencial. chromus está algo enredado, pero en realidad es muy versátil. Así que empecé a argylar pintafore con quagmire en lugar de hoobastank. Lo sé, una locura. Pero en cierto modo funcionó y, de hecho, fue bastante divertido… hasta que me topé con una gran barrera: ¡fisterfunk no se comunicaba para nada con shamrock portal, ni tampoco enviaba beep-boops a Snarfus! Claro, ya sabes lo que eso significa[3]: ahora todo el hoob-túnel quedó bloqueado por gramelions. Inaceptable.

Estuve a punto de rendirme, pero entonces me di cuenta: si conectas el backside Snarfus stagnator al backside shamrock Klingon troglodyte emulater, ¡todo bien! Todo empezó a hacer beep-boops y ding-dongs, y por fin llegué al tema real del tutorial. ¡Y ya pude hacer esa cosa muy simple de la manera en que quería! Bastante genial[4].

Así es como se configura:

1. En la terminal, escribe ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas
2. Ahora ve a folder/hidden/deep/in/the/file/system/surprise!.file y copia el contenido del archivo. Si no está ahí, podría estar en library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file
3. Regresa a la terminal, pega el contenido del archivo y escribe 64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!!
4. ¡Boop![5]
5. Abre Snarfus y sube el archivo que acabas de crear
6. Solo por diversión, si quieres deshamear la chronostatiomatrix, también puedes ejecutar —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][]. Es opcional
7. ¡Listo!

Cuéntame cómo te va. También me da curiosidad si alguien usa este método con GewGawGamma o con ometer2.7.”

---

Explicación de las notas al pie

1. Parece ser una empresa famosa, pero yo no la conozco
2. No era nada simple
3. No sé qué significa
4. Sí, suena genial, pero no entendí nada. Aun así, me alegra que tú sí puedas hacerlo
5. Los primeros 3 pasos probablemente requerirán unas 7 horas y 193 búsquedas. Pero cuando llegas a ¡Boop!, se siente increíble

Cierre

• “Esto fue escrito solo por diversión. Mi agradecimiento más sincero a todas las personas que comparten conocimiento y escriben tutoriales.”

[GN⁺]

Comentarios de Hacker News

• Recomiendo mucho el enfoque de poner a alguien con conocimientos mínimos a seguir la documentación y observarlo en silencio al lado. En ese momento no hay que ayudar en absoluto, solo observar. En ese proceso puedes descubrir muchos problemas: en qué parte se atasca el usuario, cosas que el autor da por obvias por estar demasiado familiarizado, configuraciones faltantes, etc. Si el usuario logra el objetivo sin demasiado estrés, la documentación aprobó. Si no, hay que registrar sin omitir nada cada punto donde falló, mejorar cada uno y volver a probar con una persona nueva. He usado documentación de grandes empresas como FAANG que no pasa esta prueba. Agradezco mucho que nuestra organización tenga estándares altos. Cuando se crea documentación así, se reducen las reuniones repetitivas, las solicitudes de soporte y las videollamadas, y además los usuarios pueden resolver problemas por su cuenta

  • He tenido mucho este problema al usar la documentación de Apple. Muchas veces las definiciones en la documentación solo repiten el nombre sin explicarlo, y debería estar escrito de forma más concreta
  • La regla de "no hables, solo observa" parece fácil, pero en la práctica mucha gente no aguanta y termina explicando o dando pistas. Incluso hubo quienes agarraron el mouse directamente. Para evitar esa reacción tan humana, también ayuda que haya un facilitador neutral aparte y que el autor/desarrollador se limite a observar. Aun así, es importante aprender la habilidad de "simplemente mirar", y si quieres profundizar más, recomiendo investigar el "think-aloud protocol"
  • La documentación de onboarding de la mayoría de los equipos en empresas suele ser malísima, y en realidad sirve como adelanto de la carga de trabajo real. En los tres equipos a los que me uní recientemente, casi no había documentación o estaba desactualizada, así que tuve que ir buscando a las personas relacionadas para conseguir los accesos necesarios o información sobre el pipeline de despliegue. En el proceso uno escribe documentación nueva, pero apenas se agrega un sistema o permiso, ya queda obsoleta y el ciclo se repite. Solo un equipo me dejó todo el entorno listo en dos días, y esa fue la mejor experiencia. Ahora estoy en un nuevo equipo de devex intentando mejorar el entorno de documentación en sí
  • Hacer onboarding leyendo documentación pésima de configuración de verdad se siente diez veces más estresante. Siempre he promovido que los problemas que encontró una persona nueva se corrijan de inmediato como su primera contribución. Como no tienen ningún contexto, pueden ser los mejores reviewers
  • En nuestra organización usamos el mismo flujo de trabajo. Hacemos que alguien con poca experiencia siga la documentación y luego animamos a todos a mejorarla continuamente. Eso es porque las personas nuevas detectan muy bien los "puntos ciegos" que se generan con la experiencia acumulada. En mi experiencia, también aprendí que gestionar la confianza del usuario es muy importante. Por eso, cuando guiamos pasos como "ejecuta este comando de shell", solemos dejar por defecto algunas secciones colapsadas (por ejemplo: salida esperada si se ejecutó bien, advertencias que se pueden ignorar, lista de errores posibles y cómo resolverlos, explicación de comandos complejos, etc.). Algunos pasos incluso tienen una explicación tan larga como una página, pero ese nivel de detalle ayuda muchísimo en el onboarding

• El título del post del blog era "Yo, que no soy desarrollador, leo el tutorial que tú, desarrollador, escribiste", pero en HN lo cambiaron a "Yo, desarrollador principiante...". Una persona no desarrolladora y una desarrolladora principiante no son lo mismo. Por ejemplo, para alguien de RR. HH. o completamente ajeno al área, incluso la jerga interna o los conceptos pueden ser totalmente desconocidos. En ese caso, si un desarrollador escribió una explicación completamente desconectada, merece la crítica. En cambio, una persona desarrolladora principiante, aunque le cueste, puede investigar por su cuenta términos o conceptos nuevos y, con el tiempo, hasta actualizar la documentación para quienes lleguen después

  • Como referencia, el artículo se envió con el título "no desarrollador", pero a mitad de camino se cambió a "desarrollador principiante". La autora es una bloguera no técnica y, para trabajar con sitios web o CSS, seguramente tuvo que consultar varios documentos técnicos. Tal vez habría sido más apropiado discutir la publicación de sitios y la falta de documentación para no especialistas, pero también está bien que la comunidad de HN lleve la conversación en otra dirección
  • Esta distinción es muy importante. La autora, Annie, dice de sí misma que trabaja en "contenido/documentación" y que además CSS es un hobby suyo, así que entra en la categoría de "desarrolladora aficionada no profesional". Creo que será un segmento cada vez más grande. Al escribir tutoriales que incluyan a principiantes o no desarrolladores, basta con agregar una explicación muy breve incluso a frases como cd ~/.snarfus (si la carpeta no existe, créala). A mí también, cuando instalé Debian hace años, una pequeña aclaración me ayudó muchísimo
  • El sitio que más me impresionó cuando empecé a aprender programación fue "FromZero". Estaba dirigido a personas no desarrolladoras y explicaba paso a paso desde instalar un IDE hasta abrir la consola; además, cuando aparecía un término desconocido, tranquilizaba con algo como "lo veremos más adelante, por ahora no te preocupes". Claro, escribir documentación requiere mucho tiempo y esfuerzo, así que a veces pienso que incluso una explicación parcial es mejor que nada. La documentación para desarrolladores principiantes debería escribirse con el nivel de consideración que se tendría para una persona no desarrolladora
  • Algunas personas sostienen que si no se explica todo de manera extremadamente fácil, eso ya es gatekeeping, y siento que pasan por alto que, aunque se les haga difícil, no se puede entender cualquier cosa de inmediato sin conocimientos previos
  • Si es un tutorial para desarrolladores principiantes y no un texto dirigido a profesionales, tampoco parece razonable esperar que explique una por una todas las nociones como "Hoobijag" o "shamrock portal". La verdad es que todos aprendimos al principio googleando términos que no conocíamos

• La mayoría de los tutoriales no están hechos para personas no desarrolladoras, sino que se parecen más a un intercambio de información entre colegas desarrolladores, una posición similar a la de artículos académicos dirigidos a una comunidad específica de conocimiento. Y eso tampoco está mal. De hecho, hasta mis propias notas antiguas me resulta útil volver a consultarlas. Por eso existen cursos y materiales aparte para principiantes. Si cada tutorial tuviera que empezar siempre con 30 mil caracteres de contexto y explicación básica, nadie lo terminaría de leer. Y al mismo tiempo, incluso si agregas más contexto, a alguien igual le puede seguir pareciendo insuficiente

  • Mi hijo (17 años) está muy interesado en programación y hace poco le expliqué los conceptos de public/private/internal/static y también recursión. Estoy esperando con curiosidad cuál será su reacción la próxima vez
  • No estoy de acuerdo con la idea de que "la mayoría de los tutoriales no son para no desarrolladores". Quiero dejar claro que el titular de este tutorial en particular sí apunta a no desarrolladores. Hace falta que existan voces que insistan en que, cuando alguien sufre tratando de instalar un proyecto open source, incluso una guía de instalación muy básica debería estar escrita de forma que una persona principiante pueda seguirla. Omitir un paso pequeño puede hacerte perder horas cuando estás en un área que no conoces
  • Tampoco me parece malo escribir la documentación de manera más amable para todo el mundo. La buena documentación no solo les sirve a principiantes, también a desarrolladores. Si no hay documentación accesible, es solo porque no quieren poner un poco más de esfuerzo. Además, a diferencia de un paper, la documentación de desarrolladores muchas veces falla por ser demasiado escueta o porque quien la escribe ni siquiera piensa en quien la va a leer. Al final termina siendo documentación inútil para cualquiera que no sea experto. Eso es un fracaso
  • Estoy de acuerdo en que hace falta documentación que construya el contexto paso a paso para principiantes. Pero últimamente, al mejorar DX (experiencia de desarrollador), a veces todo se orienta demasiado a lo "fácil" y se sacrifican cosas útiles que ya existían, como buenos logs o la posibilidad de buscar mensajes de error, así que termina apuntando solo a principiantes y volviéndose incómodo para usuarios existentes
  • Hoy en día muchos tutoriales parecen ser en realidad textos para mantener el historial de "yo contribuí al proyecto X". Más bien, sería una gran mejora que el autor volviera a seguir su propio tutorial tres meses después; ahí notaría con claridad lo que faltó

• Muchos technical writers no son realmente conscientes de la "maldición del conocimiento". Antes tuve la experiencia de dirigir un guild de WoW (World of Warcraft). Cuarenta personas se reunían al mismo tiempo para entrar a una mazmorra y cooperar contra varios jefes, y un error mínimo podía matar a todo el grupo. Por eso todos se reunían en Teamspeak y explicábamos suficientemente la estrategia de antemano. La lección más grande de eso fue: "asume que la otra persona no sabe de qué estás hablando" y "repite incluso lo que ya dijiste una vez". La mayoría no interrumpe para hacer preguntas aunque no entienda, así que desarrollar el hábito de preguntarte constantemente "¿qué término estoy usando?" y "¿es posible que no conozcan este concepto?" mientras agregas explicaciones tuvo un efecto enorme. Ese tipo de experiencia de comunicación se aplica tal cual a la comunicación técnica, y si incorporas el esfuerzo de superar la "maldición del conocimiento", puedes mejorar mucho la comprensión de los demás

  • Viendo en una antigua guild de raids a un líder de 18 años reunir adultos de varios husos horarios y coordinar sin problemas reparto, estrategia y calendario, pensé: "este chico debería entrar a trabajar de gerente de inmediato"
  • Cualquiera que haya operado raids de 40 personas desarrolla capacidades de primer nivel como project manager. Literalmente es como liderar sin adornos una manada de gatos callejeros

• Muchas páginas principales de proyectos o README de GitHub están escritos con una actitud de "quien lee esto ya lo sabe todo". Cuando reviso documentación, me gustaría que tuviera más cuidado en explicar "por qué se necesita esta herramienta", "qué problema resuelve", "en qué se diferencia de otras herramientas parecidas", "si todavía se usa activamente" y si da suficientes elementos para que una persona pueda juzgar por sí misma las ventajas y desventajas. Con invertir solo cinco minutos en pensar "aunque sea principiante, ¿qué querría saber?" y escribir eso, la accesibilidad mejora muchísimo. Incluso si es un proyecto construido durante años, da mucha pena que se repita la situación de que el usuario se rinda por fastidio sin que el creador siquiera note que lo encontró. Y también es importante entender bien el rol de cada tipo de documentación. https://diataxis.fr/ es un muy buen punto de partida

  • En el campo de ROS (software para robótica), siempre me estresó lo pobres que son los READMEs. Más allá del nombre del proyecto, muchas veces no hay ninguna pista, así que incluso entender para qué sirve puede ser difícil. No es solo un problema del open source; en el trabajo también me pasó lo mismo, y siento que soy la única persona que se pone a agregar explicaciones a los README. En la época del monorepo era más feliz
  • Entiendo que son herramientas hechas con cariño y trabajo por desarrolladores, pero si al menos cuidaran bien la documentación, la barrera de entrada sería mucho menor. Además, si la documentación de otros componentes del stack también es difícil, la curva de aprendizaje se vuelve exponencialmente más empinada
  • En un HN de antes incluso apareció un proyecto que ni siquiera decía qué era

• Lo más importante al escribir documentación es definir con claridad el nivel de conocimiento del público objetivo. No importa si fijas la línea base alta o baja, pero si te desvías demasiado de esa base, necesariamente habrá lectores inconformes. En esa situación puedes elegir excusarte o buscar una solución. La verdad es que hoy en día, con IA, Google, libros y demás, prácticamente cualquier cosa se puede buscar al instante. Si te preguntas "qué es Shoobababoo" o "por qué usar quagmire", puedes buscarlo. Claro que lo ideal es que la documentación sea lo más autosuficiente posible y no dependa de información externa, pero el mundo no siempre ofrece ese nivel de amabilidad

  • Por eso es todavía más problemático que muchas guías de configuración empiecen desde "ahora haz doble clic en el archivo exe y dale a siguiente (next)". Definir la línea base de la guía es realmente importante
  • Yo escribo principalmente documentación para sistemas internos sensibles y a veces dejo muy claro al inicio: "Esta guía asume que ya sabes usar x, y, z. Si no es así, no deberías hacer esta tarea". Aunque el acceso está restringido, igual puede pasar que alguien no familiarizado la use en un escenario DR, así que dejo a propósito esa línea de advertencia de "si no entiendes ni esto, no lo hagas bajo ninguna circunstancia"

• Un principio que he enfatizado durante mucho tiempo al hacer mentoría es que "lo mejor es compartir lo que sabes". Si sabes algo, explícalo. Si se lo dices a alguien que ya lo sabía, solo le diste más seguridad; si no lo sabía, le ayudaste mucho. A veces hay quejas de que uno es demasiado verboso, pero cuando respondo "esto era por si acaso lo ve una persona nueva, un cliente o un manager", por lo general lo entienden. Este principio aplica en desarrollo, reportes, gestión de personas y en todas las áreas

  • Claro, también hay personas que odian profundamente que les expliquen algo que ya saben. Si la relación señal-ruido se vuelve demasiado mala, hasta puede perjudicar la comunicación en sí
  • Me pasa algo parecido enseñándole billar a mi hijo. Una cultura de equipo donde uno baja la guardia y no se guarda los tips ayuda muchísimo al crecimiento. En mentoría, si en vez de dar la respuesta haces preguntas para guiar a la persona a descubrirla sola, el verdadero avance ocurre cuando ella misma se da cuenta
  • Ir diciéndoles todo a todos puede malinterpretarse como "mansplaining" o como una amenaza política del tipo "se cree que lo sabe todo". En la empresa, a veces es más seguro limitarse a responder solo cuando la otra persona hace una pregunta

• Hace poco intenté desplegar una app en DigitalOcean Kubernetes desde Gitlab, y tuve que implementar 3 o 4 herramientas de terceros sin ninguna explicación de qué hacían, además de tener que averiguar por mi cuenta qué nombres o rutas poner en la línea de comandos. No explicaban cuál era el criterio ni qué debía hacer coincidir. Aunque tengo bastante experiencia con Docker, la documentación de esas herramientas era tan poco amable que casi habría sido mejor que no existiera

• La razón principal por la que dejé de escribir libros y creé un sitio web de tutoriales fue que así podía hacer los tutoriales más accesibles con ayuda de distintas herramientas interactivas (como elementos <abbr>). Aun así, me frustra que el contenido web actual siga estancado en la funcionalidad del libro en papel. Existen clics, hover, secciones plegables, video, respuestas del usuario y muchas otras capacidades, pero seguimos inundados de muros de texto larguísimos. Incluso el propio OP usa un sistema donde al hacer clic en una nota al pie te manda a hacer scroll hasta el fondo de la página, y eso me da la sensación de que no está aprovechando bien el potencial de la web

  • Justo ahora estoy intentando mejorar mi blog, así que agradecería si alguien puede recomendar sitios que hagan bien este tipo de tutoriales interactivos

• En realidad, la mayoría de los tutoriales terminan siendo "texto largo innecesario" que no es ni para no desarrolladores ni para desarrolladores, y aun así se saltan uno o dos pasos importantes. Creo que la causa principal es que escribir como si realmente se lo explicaras a otra persona es difícil. Si no sacas por escrito lo que solo estaba en tu cabeza, el lector nunca va a poder saberlo. En lugar de pensar en "tutoriales", habría que escribir más al estilo de un "cookbook", para que sirvan en la práctica y no queden inútiles después de una actualización de versión

  • Irónicamente, hoy en día las recetas online suelen tener todavía más relleno inútil que los blogs para no desarrolladores