Video Summary and Transcription
La charla discute el viaje de mejorar la documentación de React y React Native, incluyendo la adición de cajas de arena de código interactivo y contenido visual. El enfoque estaba en crear una experiencia de aprendizaje más accesible y atractiva para los desarrolladores. La charla también enfatiza la importancia de construir una API humana a través de una documentación bien diseñada. Proporciona consejos para construir sitios de documentación efectivos y destaca los beneficios de contribuir a proyectos de código abierto. Se menciona el impacto potencial de la IA en el desarrollo de React, con el reconocimiento de que los ingenieros humanos todavía son esenciales.
1. Introducción y Antecedentes
Estuve despierto hasta tarde anoche asegurándome de que todas estas diapositivas estuvieran en modo oscuro solo para el planetario. Quiero asegurarme de que puedas tomar tu café y tus lattes en la oscuridad y en silencio. He hecho muchas cosas en mi larga carrera, incluyendo ser un dibujante galardonado y el animador de la API de animaciones web. Ahora estoy liderando la educación de desarrolladores en Clerk. ¿Cuántos de ustedes usan Clerk? ¿Cuántos de ustedes usan react.dev? Solía trabajar en animaciones y construir cosas geniales. Me encanta viajar por el mundo enseñando a la gente a programar y hacer cosas interactivas geniales.
Estuve despierto hasta tarde anoche asegurándome de que todas estas diapositivas estuvieran en modo oscuro solo para el planetario. De nada. Quiero asegurarme de que puedas tomar tu café y tus lattes en la oscuridad y en silencio. Sé que es demasiado temprano para esto. Es demasiado temprano. Pero te tengo. Te tengo.
De todos modos, hola. He hecho muchas cosas en mi larga career, incluyendo, tal vez no lo sepas, hace mucho tiempo fui un dibujante galardonado y solía ser como el animador de la API de animations web que solo ahora está lanzando cosas en Chrome. Y ahora, por supuesto, estoy liderando la educación de desarrolladores en Clerk. Me encanta enseñar a la gente. No puedo verte, así que vamos a tener que hacer esto con aplausos. Voy a meterte en esto hoy. Estoy estableciendo un número aquí. ¿Cuántos de ustedes usan Clerk? Dame un aplauso si usas Clerk. Eso está bastante bien. Eso está bastante bien. ¿Cuántos de ustedes usan react.dev? Puedo oír eso. De hecho, estoy obteniendo números reales de esto. 50% para react.dev. Puedo oír eso. Bien. Genial. Boop boop.
Ahora, antes de todo esto solía trabajar en, como mencioné, las animations. Construí cosas geniales como esta. No es demasiado brillante. Vas a estar bien para el resto de estas diapositivas. Ahora que hemos calibrado completamente la audiencia podemos proceder. Y me encanta viajar por el mundo enseñando a la gente a programar y hacer cosas interactivas realmente geniales.
2. Educación y Trayectoria Profesional en React
En 2018, me interesé en Vue debido a su cálida y acogedora comunidad. Aprender React fue un desafío, especialmente con la configuración de webpack y el manejo de problemas de dependencia. Sin embargo, me di cuenta de que la mayoría de los trabajos bien remunerados requerían habilidades en React, incluso para personas con experiencia. Me uní al equipo de React en Londres en 2019 con el objetivo de democratizar la educación en React. Durante la pandemia, trabajé en la construcción de nuevos documentos de React. Ahora, vamos a profundizar en los detalles.
Y por supuesto, en 2018, realmente me interesé en Vue, porque la comunidad se sentía tan cálida y acogedora. Y Sara Drasner estaba creando excelentes materiales educativos liderando su carga de documentación. Y en ese momento había intentado aprender React un par de veces, y simplemente no se me quedaba. Conseguiría un curso y dime si esto te sucedió en algún momento. Conseguirías el curso, te sentarías y pasarías como dos horas intentando pasar a través de la configuración de webpack. Y luego tendrías todos estos problemas de dependencia, y era realmente desalentador. Y tendrías suerte si llegabas al final, y aún más suerte si recordabas lo que aprendiste. Escuché esto una y otra vez de otras personas.
Pero cuando estaba buscando trabajo, noté que la mayoría de los salarios de seis cifras requerían que aprendieras React. No eran para Vue, no eran para Ember, no eran para las cosas que vi a las mujeres de mi comunidad de codificación gravitando hacia. Eran para React. Era una barrera que tenías que cruzar para entrar en ese tipo de rol. Pero esto era interesante, porque incluso para – oh, sí, creo que estamos teniendo uno de los primeros – ahí vamos – problemas técnicos del día. Muy bien. Incluso para personas con experiencia, como con grados en ciencias de la computación, dirían cosas como, oh, sabes, todavía tengo problemas para entender React a partir de la información disponible para mí. Lo sé porque los entrevisté extensamente. Y me decía a mí mismo, bueno, si React fuera tan fácil de aprender como Vue y se sintiera tan agradable un lugar para estar como esa comunidad, más personas como yo podrían obtener salarios de seis cifras, acumular riqueza intergeneracional, cambiar el mundo, cambiar el – eso suena como una muy buena palanca que podría empujar. Ahora, ¿puedo recibir un pago por hacer eso, es la siguiente pregunta.
Así que me uní al equipo de React en Londres en 2019, como defensor del desarrollador, ingeniero de documentación, híbrido. Por cierto, consejo profesional, si alguna vez vas a entrar en la gran tecnología, no tomes roles híbridos, eso es una cosa de startups, la gran tecnología tiende a tener estas escaleras de carrera y son híbridas. Tarde o temprano alguien va a venir a ti como el ojo de Sauron y te dirá, tienes que elegir uno de estos roles, y tú dirás, OK, no me inscribí para ese. Sólo un consejo, a la gran tecnología le gusta tener roles claramente definidos. De todos modos, decidí unirme específicamente con este objetivo en mente, para democratizar la educación en React para el mundo. Lo sé, suena realmente auto engrandecedor cuando lo digo en voz alta. Tenía buenas intenciones. Mis amigos me preguntaban, ¿por qué te unes? Y yo decía, porque quiero cambiar el mundo de una buena manera. Así que pasé la pandemia construyendo nuevos documentos de React con el increíble equipo de React y la comunidad. No sé cómo pasaste la tuya, pero fue algo acogedor. Y sí, vamos a hablar de eso hoy. Pero, cuando llegué a Meta, dijeron, genial, estás aquí.
3. Documentación e Insights de React Native
Pero antes de que puedas trabajar en ReactJS.org, queremos que inviertas todo este estrato en trabajar en la documentación de React Native. La gente necesitaba más material de repaso sobre React. Nuestra documentación decía, ¿te gusta React? React Native es como React, pero para el desarrollo móvil. Necesitábamos más contenido visual, más contenido en profundidad sobre temas especializados. Y, por supuesto, código interactivo. En mis encuestas, aprendí algunas cosas interesantes. El 41% de los desarrolladores de React Native venían de un fondo de desarrollo móvil. No venían de un fondo de desarrollo de React. Y había, como, un 10% que no tenía experiencia en programación, punto. Así que, estábamos haciendo muchas suposiciones, anteriormente, sobre el tipo de personas que estaban tratando de aprender React Native y los antecedentes que tenían. Uno de los primeros pasos que hicimos fue añadir interruptores de contexto literales para hablar de la experiencia personal de cada aprendiz. Los desarrolladores de Android tienen un modelo mental diferente al de los desarrolladores web. También añadimos el repaso de React, que es una masterclass inmediata para aquí es cómo funciona React. Ve. Así que, no tienes que ir hasta MDN para aprender JavaScript, para que luego puedas ir a React.js.org, para que luego puedas venir a las acciones de React Native.
Pero antes de que puedas trabajar en ReactJS.org, queremos que inviertas todo este estrato en trabajar en la documentación de React Native. Tuve la tarea de darle la vuelta a los documentos allí. Acababa de ser rediseñado, una página de inicio realmente genial con animaciones de Nat Ellis. Y yo estaba como, hmm. Bueno, se ve bien, pero obviamente los documentos no están conectando. Pero no sé nada sobre la comunidad de React Native. ¿Cómo son? ¿Qué les quita el sueño? ¿Qué es el desarrollo móvil? ¿Qué quieren? Así que, los entrevisté. De hecho, empecé a hablar con miembros individuales de la comunidad de React Native. Y realicé encuestas, y aprendí muchas cosas.
La gente necesitaba más material de repaso sobre React. Nuestra documentación decía, hey, ¿te gusta React? React Native es como React, pero para el desarrollo móvil. Bueno para ti. Muchas veces la gente en realidad no conocía React. Necesitábamos más contenido visual, más contenido en profundidad sobre temas especializados. Y, por supuesto, código interactivo. Esta es una de las grandes peticiones que tuvimos. Porque no sé tú, pero es un poco difícil montar un entorno de desarrollo móvil al vuelo. Y a veces estás simplemente resolviendo algo. Y sería bueno hacer eso justo allí en los documentos, en lugar de tener que, ya sabes, iniciar Xcode.
Así que, en mis encuestas, aprendí algunas cosas interesantes. El 41% de los desarrolladores de React Native venían de un fondo de desarrollo móvil. No venían de un fondo de desarrollo de React. Y había, como, un 10% que no tenía experiencia en programación, punto. Así que, estábamos haciendo muchas suposiciones, anteriormente, sobre el tipo de personas que estaban tratando de aprender React Native y los antecedentes que tenían. Así que, uno de los primeros pasos que hicimos fue añadir interruptores de contexto literales para hablar de la experiencia personal de cada aprendiz. Los desarrolladores de Android tienen un modelo mental diferente al de los desarrolladores web. También añadimos el repaso de React, que es una masterclass inmediata para aquí es cómo funciona React. Ve. Así que, no tienes que ir hasta MDN para aprender JavaScript, para que luego puedas ir a React.js.org, para que luego puedas venir a las acciones de React Native. Que, por cierto, era el camino de aprendizaje para muchos desarrolladores móviles que venían a React Native.
4. Mejorando la Documentación de React Native
Trabajamos con Expo para agregar cajas de código interactivo a nuestra documentación de API incompleta. A través de una masterclass de documentación con la comunidad, actualizamos la documentación de la API e incorporamos expertos de la comunidad como escritores invitados. También lanzamos el dominio React-native.dev, lo que mejoró la proporción de pulgares arriba a pulgares abajo de la documentación en un 70%.
Esto lo hizo mucho más rápido para ellos. Y trabajamos con nuestros maravillosos amigos de Expo para agregar cajas de código interactivo en cada página de nuestra documentación de API, que estaba incompleta. Pero arreglamos eso también. Debido a que esa documentación de API no se construyó a partir del código fuente, tuvo que ser editada a mano. Organizé esta maravillosa masterclass de documentación con la comunidad donde todos, revisamos juntos el código fuente y actualizamos la documentación de la API. Bastante genial. No escalable, pero genial. E incorporamos expertos de la comunidad como escritores invitados, escribimos nuestra seguridad documentación, la llenamos con hermosas ilustraciones coloridas también, que resultaron ser bastante populares. Y finalmente, utilizamos el dominio React-native.dev, en el que habíamos estado sentados durante bastante tiempo, para lanzarlo el 23 de julio de 2020. Así que ya no era github.io, barra, facebook, barra. Ahora teníamos una URL real. Parece que alguien pertenece aquí. Así que lo divertido fue que todo este trabajo, elevó la proporción de pulgares arriba a pulgares abajo de la documentación de React-native en un 70%. Todo este esfuerzo tomó alrededor de seis meses, y fue un esfuerzo de la comunidad y yo también lo hice. Es bastante bueno. Son números bastante buenos, ¿verdad? Sí, es bastante bueno.
5. Documentación de React y Retroalimentación de la Comunidad
La documentación de React tiene una gran responsabilidad. El 86% de los desarrolladores de React encuestados comenzaron con nuestros Docs. Mucha gente está aprendiendo React primero a través de la documentación. El esfuerzo comenzó en mayo de 2020. Comencé con la comunidad, entrevistándolos para entender sus necesidades y pensamientos. Los resultados fueron similares a React Native, con una solicitud para enseñar primero los componentes de función y mejorar la referencia de los hooks.
Entonces, con ese éxito, era hora de trabajar en React. No lo conocíamos como react.dev en aquellos días. Lo conocíamos como reactjs.org hace mucho, mucho tiempo. Ahora, la documentation de React tiene una gran responsabilidad. El 86% de los desarrolladores de React encuestados comenzaron con nuestros Docs. Por supuesto, estas también eran personas que respondían encuestas en Twitter y a través de nuestros Docs, así que sabes, podrían estar un poco sesgados. Pero aún así, mucha gente está aprendiendo React primero a través de la documentation. Esos números probablemente se han sesgado un poco más a medida que la gente se ha estado moviendo más y más hacia YouTube.
Pero el esfuerzo realmente comenzó el 27 de mayo de 2020. Esta es en realidad una foto de mi Diario de Atención Plena de Kurzgesagt. Literalmente dice que, jugué Starcraft en el trabajo e inicié la Revisión de los Materiales de Educación de React, y tuve la oportunidad de hablar con Amanda y Britney en el trabajo. Eso fue genial. Cosas por las que estoy agradecido. Muy bien. Fue el comienzo de la pandemia. Y al igual que con React Native, pensé, voy a empezar con la community. Voy a entrevistar a la community. Quiero saber qué quieren. ¿En qué están pensando? Creo que mucha gente hace suposiciones sobre la community en la que creemos que crecemos en ella, creemos que la conocemos. Pero está cambiando constantemente. Incluso cómo la gente aprende hoy es diferente de cómo aprendieron en 2020. Si volviera a hacer esta encuesta, me sorprendería. Es importante siempre verificar lo que crees que son verdades sobre las personas que conoces y con las que trabajas.
Vale. ¿Qué dijeron? Bueno, los resultados fueron muy similares a React Native. ¿Podrían enseñarnos... excepto por supuesto con este, podrían enseñarnos primero los componentes de función? Todo son clases. Clases por todas partes. La documentation de los componentes de función está en tres lugares separados. Por favor, deténganse. Referencia de Hooks.
6. Mejorando la Documentación y la Representación Visual
La documentación necesitaba una revisión, incluyendo una actualización de la arquitectura de la información y la adición de más contenido visual y código interactivo. El viaje comenzó con una sesión de lluvia de ideas con Dan Abramoff durante la pandemia, lo que llevó a la creación de React head, una representación visual de React. Los garabatos y bocetos jugaron un papel crucial en la comunicación de conceptos e ideas. La ilustración final representaba a React como un camarero que traía componentes de la cocina.
Una vez más. ¿Dónde estaban las dependencias? Bueno, esa es una buena pregunta. Tienes que saber qué palanca secreta de la puerta tirar para encontrarla o memorizar todas las ubicaciones de las menciones de los hooks. Los documentos se leían cada vez más como ensayos de código. Necesitaban una revisión significativa de la architecture de la información. Y por supuesto hubo una solicitud de más contenido visual. Y por supuesto código interactivo. La gente quería poder jugar con los ejemplos. No querían tener que construir, ya sabes, todo un entorno de desarrollo y crear un nuevo repositorio.
Muy bien. Todo esto comenzó con una sesión de lluvia de ideas con Dan Abramoff. Fue dentro de las directrices del confinamiento. Esto era totalmente legal. Conseguimos ir durante uno de los descansos. Usamos postales. Había muchos garabatos. Todavía los tengo. Creo que son realmente geniales. Algún día probablemente irán a un museo. Podría ser un museo sobre Dan. Lo averiguaremos. Y Dan y yo tendíamos a comunicarnos con bocetos. Y debido a eso, hice un nuevo amigo durante la pandemia, conocido como React head. Así que garabatear fue una parte muy importante de mi viaje con React. Dibujaría un concepto y se lo mostraría al ser humano, como, ¿lo entendí bien? ¿Es así como funciona esto? Esto llevó a algunas cosas bastante geniales, como esta extraña notación visual en la que estaba trabajando para la state management de React DevTools. No preguntes. No llegó a ninguna parte. Pero empecé a dibujar a este pequeño tipo que estaba inspirado en IKEA, mi tienda de muebles favorita de todos los tiempos, y era algo así como, ¿qué pasaría si tuviéramos a React comunicándose con nosotros, sin palabras, explicando visualmente cómo hacer estas cosas. Así que este React head se convirtió en mi pequeño co-presentador cuando estaba usando estas notas para comunicar lo que había aprendido de Dan. Y finalmente terminamos describiendo a React como un camarero que traía componentes a la gente desde la cocina, y puedes ver que evolucionó a este tipo de ilustración más acabada.
7. Escribiendo un Libro Interactivo y Tono Internacional
Terminamos con esta enorme hoja de cálculo de contenido, como escribir un nuevo libro desde cero sobre React. Tomamos un enfoque completamente nuevo para enseñar React, quemando los documentos hasta el suelo. React Head hizo su debut, y Maggie Appleton construyó un increíble sistema de diagramación. Queríamos asegurarnos de que todos los ejemplos usaran un tono internacional, celebrando la herencia humana común.
Y todavía puedes ver estos en los documentos. Fueron muy divertidos.
Bueno. Terminamos con esta enorme hoja de cálculo de contenido. Si alguna vez te preguntas, como, por qué los documentos tardan tanto, fue como escribir un nuevo libro. Fue como escribir un libro desde cero sobre React. Porque el equipo creía que teníamos que tomar un enfoque completamente nuevo para enseñar React. Esto no era solo mover algunas cosas con, como, React Native. Estamos quemando los documentos hasta el suelo. Estamos empezando de nuevo. Fue como escribir un libro, un libro interactivo.
Mi tipo de libro favorito. Fuimos a beta, el 8 de diciembre de 2020, para que la community pudiera acceder a esta nueva información. Obviamente, tomó un tiempo. React Head hizo su debut. ¡Yay! Buen React Head. Y Maggie Appleton construyó un sistema de diagramación. Yo había dibujado diagramas. No querrías verlos. Son indescifrables. Pero Maggie construyó este increíble sistema de diagramación que realmente ayuda a dar sentido a las cosas. Una de mis partes favoritas es que Sylvia Vargas ayudó con... Queríamos asegurarnos de que todos los ejemplos usaran un tono internacional. No hay referencias a Star Wars, porque eso es cultura pop estadounidense. ¿Es trabajo de React exportar la cultura pop estadounidense al resto del mundo? No, déjalo a Disney. Así que se nos ocurrió esta lista de cosas internacionales que toda la humanidad puede celebrar. Como la cocina. Arte. Ciudades. Y, ya sabes, solo las cosas que son patrimonio humano común.
8. Ejemplos Interactivos y Repetición Espaciada
Sylvia de la comunidad tomó la lista y creó ejemplos que celebran a los grandes pensadores a lo largo de la historia. Aprender React se hizo más fácil con las masterclass interactivas, eliminando el tiempo de configuración y centrándose en la sintaxis. La repetición espaciada es la clave para un aprendizaje efectivo, ya que fortalece las vías neuronales. Nuestro objetivo era recrear esto con ejemplos editables, permitiendo la práctica instantánea de la sintaxis sin configuración.
Y Sylvia era simplemente una persona realmente genial de la community, entró, tomó esa lista, y la llevó a cabo. Y es por eso que tienes estos ejemplos realmente geniales que celebran todo tipo de grandes pensadores a lo largo de la historia humana.
Sí, es como ir a la escuela, mientras vas a la escuela para React. Y por supuesto, code sandbox nos ayudó a hacer posibles estas masterclass interactivas. Estas fueron el verdadero cambio de juego. Mientras que anteriormente aprender React, pasar de cero a hello world, tomaría como una hora de configuración, y más vale que todas las instrucciones y el tutorial fueran compatibles con el sistema que estabas utilizando, con cualquier cosa que tu trabajo diario te tuviera corriendo. No. Aquí, todo lo que tenías que cuidar era la sintaxis. Y ahí es donde estaba la magia para React, y eso es lo que queríamos compartir con la gente.
Las personas aprenden haciendo. La formación en el trabajo, todos sabemos que la formación en el trabajo superará a un título universitario en esta línea de trabajo cualquier día. ¿Pero por qué es eso? ¿Por qué es que el conocimiento teórico no es tan bueno como el conocimiento que obtienes de haber estado en el campo? Todo se reduce a la repetición espaciada. Hay un gran libro llamado Make It Stick. Puedes leerlo si quieres, pero voy a resumirlo para la audiencia, porque todavía estás tomando tus cafés aquí. Básicamente la idea es hacer cuestionarios. La razón por la que tus profesores en la escuela te hacen cuestionarios todo el tiempo es porque te obligan a recordar y usar el conocimiento una y otra vez hace que esos caminos se graben realmente en tu mente. Hace que esas neuronas se fusionen. Así que se convierte en un músculo mental que no puedes dejar de usar. Los ingenieros con los que trabajé en Meta, podían mirar un patrón de código y simplemente adivinar lo que estaba haciendo. No con la lectura, sino simplemente viendo su forma, porque estaban haciendo esa repetición espaciada día tras día. ¿Cómo podríamos recrear eso con la documentation? Bueno, íbamos a hacerlo. Invertimos en la construcción de estos ejemplos editables que permitían a estas personas empezar justo allí con la sintaxis en cero segundos. Sin configuración del entorno. Sin dependencias con las que luchar. Solo haces esto y eso sucederá. Y eso era un video y debería haber presionado el botón del clicker para hacerlo funcionar. Ahora está funcionando. Tuve que volver a grabar esto anoche. Dame un respiro. Pero de todos modos, de todos modos.
9. Desafíos y Retroalimentación del Usuario
Pero estas cajas de arena nos permitieron enviar algo que llamamos desafíos. Los desafíos se inspiraron en los entrenadores de React en línea como Josh Comeau, que tendría lecciones seguidas de cuestionarios. Al final de cada lección, habría desafíos para resolver. Preguntar a personas reales a través de encuestas confirmó el éxito de la nueva documentación de React. El 16 de marzo de 2023, se enviaron los documentos completos con más de 600 ejemplos interactivos.
Pero estas cajas de arena nos permitieron enviar algo que llamamos desafíos. Ahora, los desafíos se inspiraron en los entrenadores de React en línea como Josh Comeau, a quien vas a escuchar más tarde, que haría estas cosas geniales donde tendrías una lección que seguirías y un cuestionario al final y pasarías el cuestionario. Pasas a la siguiente lección. Pero no queríamos impedir que la gente pasara a la siguiente lección porque forzar a la gente por un camino de aprendizaje lineal en Internet no funciona. La gente entra en una página, busca respuestas, se va. No puedes obligarlos a hacer ningún tipo de prueba. Pero, al final de cada lección, habría este desafío de cosas que el equipo central de React había notado que la gente estaba tropezando. Preguntas que Dan había respondido una y otra vez en Twitter. Pero estos desafíos realmente darían a la gente la oportunidad de resolver esos problemas al final de la lección para que pudieran familiarizarse con el patrón del código.
OK, eso suena genial, pero ¿cómo sabemos si todo esto está funcionando, verdad? ¿Cómo lo sabemos? Bueno, como me gusta decir, pregunta a personas reales. No pienses, no adivines, no mires una hoja de métricas y digas que ese número parece que está subiendo. Supongo que es algo bueno o malo. No hagas eso, no hagas eso. Solo pregunta a la gente. Si preguntas a la gente, te dirán todo lo que quieres saber. En las pruebas alfa, los usuarios, yo sería como hola, llena esta encuesta antes de que tengas la oportunidad de ver el nuevo sitio. Y luego una semana después, sería como hola, lo has visto. ¿Ahora podrías llenar esta otra encuesta? Y la gente era tres veces más propensa a recomendar la nueva documentación de React después de haberla usado que a recomendar la antigua documentación cuando entraron. Eso fue bastante agradable. Eso es teóricamente como, OK, podemos enviar esto, supongo. Íbamos a enviarlo de todos modos, pero es bueno saberlo. Entonces, el 16 de marzo de 2023, los documentos finalmente estaban completos, se añadieron todos los tutoriales, las referencias de la API estaban completas. Puedes quitar el banner de mira los documentos beta de la parte superior del antiguo sitio de ReactJS. Por cierto, todavía existe si quieres aprender sobre clases. Todavía está ahí. No te preocupes. No te preocupes, siempre estará ahí, aunque no se actualizará. Y boom, envía el nuevo React.dev con una nueva y brillante página de inicio. Que se ve bastante bien en este planetario, si puedo decirlo yo mismo. Los documentos se enviaron con más de 600 ejemplos interactivos.
10. Construyendo una API Humana
Me siento bastante bien con eso. Y las ilustraciones, las cajas de arena interactivas probadas en la documentación de React Native. Continuaron, cambiaron la forma en que enviamos la documentación de React. Me gusta pensar en estas documentaciones no como palabras escritas. Me gusta pensar en ellas como una API humana. Hay un largo camino desde la persona que construye la herramienta hasta la persona que maneja la herramienta. Y cuanto más corto hagamos ese camino, más rápido podremos construir el futuro. Siempre recuerdo una de las famosas citas de Sarah Drasner, que las personas que encuentran malas documentaciones simplemente se van. Se van de tu comunidad, se van de tu producto, se rinden. Entonces, ¿cómo construyes esa API? Quería darte algunos consejos profesionales. Número uno, quieres configurar un sitio. Usa tus palabras.
Me siento bastante bien con eso. Y las ilustraciones, las cajas de arena interactivas probadas en la documentación de React Native. Continuaron, cambiaron la forma en que enviamos la documentación de React. Realmente quiero agradecer a la comunidad de React Native por toda su ayuda. Porque muchas de las ideas que probamos allí terminaron incorporándose en los documentos de React. Este tipo de esfuerzos educativos siempre se construyen uno encima del otro. Siempre estamos empujando como formadores y educadores cómo hacer las cosas incluso mejor que la última generación.
Durante ese período de beta, 8 millones de aprendices tuvieron acceso a estos documentos. Espero que te encanten ambos. Pero me gusta pensar en estas documentaciones no como palabras escritas. No como documentos secos o un manual de usuario. Me gusta pensar en ellos como una API humana. ¿Cómo transferimos el conocimiento de la mente de un ingeniero central a la mente de un desarrollador de implementación? Hay un largo camino desde la persona que construye la herramienta hasta la persona que maneja la herramienta. Y cuanto más corto hagamos ese camino, más rápido podremos construir el futuro.
Me gusta pensar en ello como construir una redada humana, donde estoy copiando información de una mente a la otra. Puedes ser realmente espeluznante con esto si eres un artista de la propaganda. Aunque yo no uso mis poderes para el mal. Así que siempre recuerdo una de las famosas citas de Sarah Drasner, que las personas que encuentran malas documentaciones simplemente se van. Se van de tu comunidad, se van de tu producto, se rinden. Porque esa longitud, ese camino desde la concepción de la herramienta, no importa cuán útil sea, era simplemente demasiado largo. Fue demasiado difícil para ellos obtener ese conocimiento. Entonces, ¿cómo construyes esa API? Quería darte algunos consejos profesionales. Sé que tenemos algunas personas que están manteniendo grandes recursos en la audiencia hoy. ¿Cómo construyes tu propia API humana? Estas son las recomendaciones que te voy a dar si te interesa esto. Número uno, quieres configurar un sitio. Usa tus palabras. Puedes usar un readme en Github, eso está bien. Github no es lo más buscable o localizable. Probablemente quieras configurar un sitio. Así que probablemente estás como, oh Dios mío voy a construir un sitio personalizado va a ser increíble.
11. Construyendo Sitios y Equilibrando Contenido
Puedes pasar mucho tiempo construyendo un sitio, pero el propósito es transmitir conocimientos. Utiliza soluciones listas para usar como Docusaurus o Starlight de Astro. La documentación de React se construye en un sitio personalizado de Next.js, mientras que la documentación de React Native y Relay utiliza DocuSource. Equilibra lo que escribes y considera usar el enfoque sistemático llamado Diataxis para la documentación y la redacción.
Detente ahí mismo. No. Creo que puedes pasar mucho tiempo construyendo un sitio. Probablemente podríamos haber enviado los documentos seis meses antes si simplemente hubiéramos usado el antiguo sitio. Hubo muchas ganancias. Pero, ¿era realmente el punto central, era el propósito enviar documentos o enviar un sitio? Tenlo claro, estás tratando de transmitir conocimientos. Es fácil configurar un gran sitio hoy en día, a menos que tengas una razón real por la que necesitas construir un sitio personalizado por alguna razón, simplemente ve con algo listo para usar como Docusaurus o Starlight de Astro.
Solía pensar que los documentos de React o los documentos de Stripe eran los mejores documentos del mundo. Así que sé, tengo que decir, me quito el sombrero ante el equipo de Astro, tienen como 800 personas trabajando en documentos en su comunidad todo el tiempo, y han evolucionado cómo se pueden hacer los documentos, y puedes obtenerlo todo listo para usar con su proyecto Starlight. Así que un saludo al equipo de Astro y al equipo de Starlight específicamente. Aquí, los documentos de React, a la gente se le pregunta esto mucho. Entonces, ¿en qué se basaron exactamente el sitio de React y el sitio de React Native? Bueno, la React Native y la documentación de Relay se construye utilizando DocuSource. Pero la documentación de React se construye en un sitio personalizado de Next.js. Probablemente podríamos haber sacado el contenido más rápido si nos hubiéramos quedado con la construcción de Gatsby que teníamos antes, pero queríamos ver si podríamos haber construido algo incluso más rápido para iterar desde el backend, como para que los ingenieros vayan y escriban documentación. Así que se nos ocurrió un flujo ligeramente diferente. Tu experiencia puede variar. Elige lo que quieras. Las personas usan lo que quieren. Paso número dos, equilibra lo que escribes. Muchas veces, cuando estamos escribiendo para una audiencia, tendemos a exagerar. Lanzamos ensayos de código. Cuando estás trabajando en un producto por primera vez, cuando estás construyendo algo, quieres compartir y quieres compartir todo lo que puedas. Eso es genial hasta cierto punto. Pero en algún momento, quieres organizarte con tus pensamientos. Quieres pensar en cómo estás compartiendo y qué estás compartiendo. Hay este gran sistema llamado Diataxis. No lo estoy pronunciando correctamente. Puedes buscarlo. De todos modos, es un enfoque sistemático para la documentación y la redacción.
12. Referencias API y Diseño de Contenido
Es popular. Probablemente esto sea lo mejor para la mayoría de nosotros. Comienza con tus referencias API, luego explica cómo funciona todo con descripciones conceptuales. Los tutoriales son guías paso a paso, y las guías proporcionan información adicional. Automatiza lo que puedas. Usa JS doc para transformar comentarios en referencias API. Las pruebas y la documentación van juntas como el queso y las galletas. Interésate por el diseño de contenido.
Es popular. Hay otros modelos, como DITA de IBM, que es simplemente excesivo para cualquier cosa en la que estés trabajando, te lo aseguro. Probablemente esto sea lo mejor para la mayoría de nosotros.
Permíteme darte mi forma de pensar al respecto, que es como una pirámide de contenido. Comienzas con tus referencias API, luego explicas cómo funciona todo con tus descripciones conceptuales. Obtienes tutoriales que son como guías paso a paso. Y al final, tienes tus guías, que son como el cajón de paquetes de información. Ve a leer sobre ello. Te alegrará haberlo hecho. Vas a pasar más de tu tiempo enfocándote en lo que importa.
Lo importante es, siempre y cuando tengas tus referencias API bien aprendidas y en su lugar, tu community probablemente pueda ayudarte a escribir el resto de esa información. Pero si no les das una referencia API completa y correcta, no pueden ayudarte. Así que asegúrate de que eso sea tu prioridad número uno. Automatiza lo que puedas. No pases todo tu tiempo escribiendo. Puedes usar algo como JS doc para transformar tus comentarios en referencias API. Puedes hacer esto muy rápido. Hay como plugins para usar esto con DocuSource. Adelante.
Se ha invertido en código de ejemplo impulsado por pruebas, por cierto, en su documentation, y sigue siendo uno de los paradigmas de documentación a prueba de futuro que me gusta sacar. Las pruebas y la documentation van juntas como el queso y las galletas, en mi opinión. Forjan una promesa a los usuarios de deliciosidad. No, estoy bromeando. Forman una promesa a los usuarios de que cuando hacen una cosa determinada, pueden esperar ciertos resultados. Así es como se sienten las personas cuando están usando tu producto. Así es como se sienten cuando están aprendiendo tu producto también.
Y por último, interésate por algo llamado diseño de contenido design. Este es un pequeño campo de experiencia generalmente asociado con la user experience y el marketing. Pero hay algunos libros geniales sobre documentation. Docs for Developers es una rápida introducción para escribir mejor, pero en términos de diseño de contenido design, Everyday Information Architecture de Lisa Maria Marquis, es un libro realmente bueno para pensar en cómo estás organizando tu contenido para ser entendido por otras personas.
13. Construyendo Equipos, Uniendo Comunidades y React.dev
Si estás pensando en construir un equipo, consulta el libro 'Leading Content Design' de Rachel McDonald. Únete a la comunidad Write The Docs en writethedocs.org para obtener consejos y apoyo. Nos vemos en el Barcade esta noche, donde puedes ganar un Nintendo Switch. Gracias por tu apoyo y disfruta de React.dev. ¿Cuál es tu raza preferida en StarCraft? Son para los microgestores, te hacen moverte más rápido.
Y si realmente estás pensando, hombre, tengo que construir un equipo, Leading Content Design es un gran libro también de Rachel McDonald. Y por último, únete a una community, haz algunos amigos. Hay una community llamada Write The Docs, writethedocs.org. Son un gran grupo de personas que han resuelto muchos de estos problemas muchas veces y pueden darte buenos consejos y sugerencias si este es tu trabajo.
Bueno, creo que eso es todo por mi parte hoy. Solo quería decir, nos vemos en el Barcade esta noche. Sí, hay un Nintendo Switch, pero lo más importante, el empleado ha traído estas fabulosas riñoneras. ¡Woohoo! Está bien. Sí. Entonces, obviamente es un evento muy a la moda aquí porque hay camisetas, camisetas de edición mito riñoneras elegantes, todo el swag que tu corazón desea para la pasarela de Nueva York. Así que muchas gracias. Nos vemos en el Barcade esta noche y no estaré venciendo a todos en Pac-Man. Tengo que darte la oportunidad de ganar un Nintendo Switch. Ya tengo uno. Muchas gracias. Espero que te encante React.dev. Fue un trabajo de amor de tantas personas. Realmente agradecido por todo el esfuerzo que todos han puesto en enseñar al mundo a pensar y react a lo largo de los años.
¿Cuál es tu raza preferida en StarCraft? Zerk. Oh, está bien. Muy bien. Agradable. No soy una persona de StarCraft, pero ¿es eso una referencia al tipo de Toy Story que hacer? Son realmente asquerosos. Oh. Vale. Son asquerosos, y requieren muchos clics por minuto para usar correctamente. Son para los microgestores, esencialmente. Vale. Y tienes que... Te hacen moverte más rápido, por eso me gustan, porque era un desafío moverse más rápido, planificar menos, moverse más rápido.
14. Documentación de React Native y React
Los equipos de React Native y React estaban previamente divididos, por eso la documentación estaba separada. Sin embargo, ahora los dos equipos son un solo equipo de React, con el objetivo de tener una comunidad unificada.
Sí. Eso es realmente genial. Increíble. Vale. Esa fue una gran pregunta. Gracias, quienquiera que haya hecho esa pregunta. Tienes un buen fan de StarCraft en la audiencia. ¿Por qué la documentación de React Native está separada de la documentación de React, aunque la web y nativo comparten el mismo paquete central? Esa es realmente una muy buena pregunta. Y diría que se reduce a, en su momento, cuando yo estaba allí, y esto ya no es el caso, los equipos de React Native y React estaban muy divididos, por lo que la documentación reflejaba la división en el pensamiento, y la división en la organización del equipo, así como, ya sabes, no siempre escuchamos a React Native y React en la misma frase. Las dos comunidades son muy diferentes. La comunidad de React Native es una comunidad de desarrollo móvil cross-platform, y la comunidad de React tiende a ser más basada en la web, pero es cierto que el mismo paquete central impulsa a ambos. Es solo que la comunidad no parece de esa manera. Pero ahora los dos equipos son un equipo de React. Un React, por cierto, va a ser mi próximo eslogan que voy a usar en estas conferencias un mundo, un React. Xbox uno. React uno. Sí. Entonces, quizás eso cambie.
15. Comenzando con la Escritura y Documentación
Para comenzar con la escritura o documentación, encuentra algo que te guste y contribuye a proyectos menos populares. Escribir entradas de blog o en tu propia plataforma puede aumentar tu marca personal. Trabajar con los propietarios de repositorios oficiales y contribuir a proyectos de código abierto puede proporcionarte una valiosa experiencia y referencias para tu currículum. La comunicación también es una habilidad crucial. El trabajo en código abierto es una excelente manera de ganar experiencia y establecer conexiones en la comunidad de desarrollo. El concepto de React más difícil de enseñar es subjetivo y puede variar para diferentes individuos.
Sí, absolutamente. Entonces, esto es un poco abierto, oh, lo siento, no es el que quería, espera, espera, espera, ese es el que quiero. Bueno, entonces la pregunta es ¿por dónde empezar? Y yo diría que tal vez lo amplíes a, ¿hay alguien que quiera empezar a hacer escritura de artículos o documentation? Como, ¿cómo empiezas? Yo estaba como, ¿cómo empiezas con React? Acabo de decírtelo. Bueno, sí, está bien. Ve a react.dev si quieres empezar con React, pero es bueno para tu career escribir. ¿Cómo empiezas a enseñar? Sí, exactamente. ¿Cómo empiezas a documentar? Bueno, honestamente el mejor lugar para empezar, en mi opinión, es encontrar algo que te guste. Todos tenemos algo que nos gusta, como una herramienta que no podemos dejar de usar o un proyecto de código abierto que adoramos. Y piensa en el que no es el más popular. Piensa en alguien que no es la chica más bonita de la sala. Y encontrarás que esas personas probablemente estarían muy contentas si vinieras y donaras un poco de tiempo para escribir un tutorial o para escribir algunas entradas de blog. Pero siempre digo, las entradas de blog son geniales. Escribir en tu propia plataforma es genial. Es genial para aumentar tu marca personal, que todo el mundo está haciendo, que es la capitalización de uno mismo, con lo que no estoy de acuerdo. Pero, ya sabes, gracias a quienquiera que... Vamos, capitalización de uno mismo. Pero diré, si vas y trabajas con los oficiales, como los propietarios del repositorio, y dices hey, me encanta tu proyecto, me encantaría mejorar tu archivo readme, lanzar un pequeño sitio de docusource con algunos de los tutoriales que he estado pensando, suelen estar muy emocionados de que lo hagas. Una vez que consigas esos cuadrados verdes en GitHub. Sí. Y algo que poner en tu currículum. Exactamente. Otra gran habilidad, la comunicación. Oh, eso también es importante. Todos, como ahora mismo, es un momento un poco aterrador en el mundo del desarrollo. Sí, eso es cierto. Si quieres obtener experiencia que puedas poner en tu currículum mientras todavía eres relativamente nuevo en la community, el trabajo en código abierto es la manera de hacerlo. Tienes la oportunidad de trabajar con alguien, sin sueldo generalmente, pero pueden avalarte en una situación de empleo. Muy bien. Entonces, ¿cuál fue el concepto de React más difícil de enseñar? Oh, hombre. Siento que esa es una pregunta complicada.
16. IA y Desarrollo de React
¿Use-effect? Sí. Es use-effect. Siempre es use-effect. React, olvídate, por cierto. ¿Cómo afectaría la posible aparición de la IA al desarrollador de React? Bueno, no tendrás que pensar demasiado en recordar todas tus dependencias en el futuro, porque React es 100% comprensible por los robots. La IA ayudará a los desarrolladores de React a ser más eficientes, pero aún estamos lejos de que el contenido generativo reemplace a un ingeniero.
¿Use-effect? Sí. Es use-effect. Es use-effect. Siempre es use-effect. Es como, ¿cómo enseñas una vía de escape? Sí, sí. Creo que mi respuesta exacta en un momento fue, ¿por qué no simplemente damos a la gente un compilador? Oh, esa es una idea. Sí. Me olvidé de eso. Hay un pequeño compilador en camino, así que estoy emocionado por eso. Es como, oh, genial. Menos para enseñar. Correcto. React, olvídate, por cierto. Muy bien. Entonces, en realidad, pasando al siguiente tema, ¿cómo afectaría la posible aparición de la IA al desarrollador de React? Hombre. ¿Cómo afecta la IA a todos nosotros? Todo. Siento que esa es una pregunta muy existencial. Bueno, no tendrás que pensar demasiado en recordar todas tus dependencias en el futuro, porque React es 100% comprensible por los robots, así que la buena noticia es que probablemente hará nuestras vidas más fáciles. Porque no tendremos que recordar todas las trampas y todas las cosas. Copilot nos lo recordará. Exactamente. Realmente creo que la IA ayudará a los desarrolladores de React a ser más eficientes. Creo que aún estamos lejos de un punto en el que el contenido generativo pueda reemplazar a un ingeniero, pero ciertamente será, creo, una herramienta valiosa para ayudarnos a componer la interfaz de usuario en lugar de, creo, nuestra metodología muy bruta que tenemos que hacer hoy. Muy bien. Muchas gracias, Rachel. Un fuerte aplauso.
Comments