Cómo MDX es un cambio de juego para la Documentación de tu Proyecto React

Rate this content
Bookmark
SlidesGithub

La documentación es esencial para cualquier proyecto y realmente puede "hacerlo o romperlo". Sin embargo, la documentación requiere tiempo para redactar y a veces puede ser olvidada, o las actualizaciones y enmiendas a ella quedan atrás a medida que avanza el proyecto. Además, crear tu documentación con Markdown tiene sus limitaciones, por lo que es posible que no termines con el resultado que deseas o que tu colaborador necesita.


Al usar MDX puedes combinar Markdown con código e integrarlo en tu proyecto React. La documentación se convierte en un proceso más eficiente y fluido y, ¿me atrevo a decirlo... divertido?

28 min
08 Dec, 2023

AI Generated Video Summary

Una buena documentación es crucial y puede hacer o deshacer un proyecto. El boca a boca es importante en la industria, y una gran documentación puede atraer usuarios. MDX es una herramienta poderosa para escribir documentación, permitiendo la personalización y reutilización de componentes. La documentación debe ser tratada como código, con pruebas y mejora continua. El uso responsable de la IA es importante, y se debe utilizar un enfoque equilibrado para la documentación, incluyendo comentarios en línea y diferentes formatos.

1. Introducción a Docs con MDX

Short description:

¡Hola, React Day Berlin! Hoy, hablaré sobre Docs con MDX y cómo puede ser un cambio de juego para tu proyecto. La buena documentación es crucial, pero no muchas personas quieren escribirla. La documentación incorrecta y desactualizada me frustra. Mejoremos los números al final de mi charla. Los documentos son tan importantes como el código. Recuerda, cada solicitud de extracción con cambios de código también debería tener pruebas y documentos.

Muchas gracias por esa cálida bienvenida. Bueno, hola, React Day Berlin. Mi nombre es Eddie Chow y estoy súper emocionado de geek con ustedes hoy sobre Docs con MDX y cómo puede ser un cambio de juego para tu proyecto.

Todos queremos buena documentación, pero parece que no muchas personas quieren escribirla. Me frustro cuando los documentos no existen. Y también me frustro cuando tienen un ejemplo de hola mundo. Quiero un ejemplo del mundo real. ¿Pero sabes lo que realmente, realmente me molesta? Cuando la documentación es incorrecta y está desactualizada. Y desafortunadamente, sucede con demasiada frecuencia. Y permíteme aclarar, por bueno, solo quiero decir correcto, actualizado, y se ve bien. No creo que sea demasiado pedir.

Quiero decir, ¿a quién le gusta leer buena documentación? Levantemos las manos. Quiero decir, esperemos que la mayoría de nosotros. Genial. Muchas gracias. Genial verlos a todos despiertos también. Como dije, nada sofisticado, es lo que esperamos. Quiero decir, ¿a quién le gusta escribir documentación? Bueno, algunas personas, algunas personas no están seguras. Bueno, esperemos que podamos mejorar esos números al final de mi charla.

Los documentos son tan importantes como el código. Y si hay algo que debes recordar de toda esta charla, por favor recuerda eso. Podríamos no tratarlo de esa manera, sin embargo. No obtenemos la misma emoción. Y tampoco obtenemos el mismo reconocimiento de nuestros pares. Cuando alguien dice, escribí esta característica genial, utilicé la biblioteca X, y todos están como, oh sí, genial. Y si alguien dice, documenté la característica X, literalmente silencio, no obtienes ese mismo reconocimiento. Y creo que eso también tiene un papel que jugar. Pero esperemos que todos podamos estar de acuerdo en que la documentación es importante, y es nuestra responsabilidad tener buena documentación. Las pruebas también son realmente importantes, pero eso es una discusión aparte, y hablamos de eso ayer aquí en TestJS. Así que creo que cada solicitud de extracción que tiene cambios de código también debería tener pruebas y documentos.

2. Importancia de la Documentación

Short description:

¿Por qué es importante la documentación? La documentación desactualizada puede ser peor que no tener documentación. Puede confundir a los usuarios y causar frustración. Al igual que montar en bicicleta sin frenos, la documentación debe ser confiable. Los pasos faltantes en la documentación pueden llevar a errores y confusión. Es importante contribuir a los proyectos de código abierto revisando y mejorando la documentación.

¿Por qué? Porque todo debe ser revisado. ¿Qué es peor que no tener documentation? Sí, hay algo peor que no tener documentation. La documentation desactualizada. ¿Por qué? Porque la gente confía en ella. Entonces, cuando algo sale mal, es aún más doloroso. Estamos guiando a las personas por el camino equivocado, por lo que no tener documentación puede ser mejor. Las personas saben que deben mirar el código, o intentar descifrarlo, o llamar a un amigo.

¿Alguna vez has montado una bicicleta sin frenos? Yo sí lo he hecho. A principios de este año en Bangkok, estábamos en un hotel, queríamos ir al parque, y nos dijeron que podíamos tomar prestadas sus bicicletas. Pero no tenían frenos. Pero como sabíamos que no tenía frenos, fuimos más despacio. Me aseguré de que Sarah fuera delante, para poder usarla para detenerme. No, solo estoy bromeando. Pero si una bicicleta tiene frenos, esperas que funcionen. Y lo mismo ocurre con la documentation.

Quiero decir, ¿cuántos de ustedes han visto esto antes? Estoy seguro de que lo han visto muchas veces. Mi proyecto principal, y luego no hay documentation. Ese es un escenario. Otro escenario es la documentación con pasos faltantes. Espero que algunas personas puedan gritar cuáles son los dos pasos que faltan aquí. Sí, antes de instalar las dependencias, navega al nuevo directorio que fue creado por el clon de Git, luego instala las dependencias y luego ejecuta npm run dev. No hay nada malo con esto. Esto no es incorrecto. Solo faltan algunos pasos. Si alguien obtiene un error en ese segundo paso y lo busca en Google, probablemente obtendrá, ya sabes, intenta instalar las dependencias. Bien, package.js no se encuentra. Correcto, navega al directorio, instala las dependencias. Y llegarán allí porque esto es genial. Y por cierto, verás esto en muchos proyectos de código abierto, por lo que una excelente manera de contribuir es revisar la documentation y no hacer suposiciones porque si estás familiarizado con proyectos como este, entonces sabrás qué comandos ejecutar. Pero las personas que son nuevas en la tecnología o en el proyecto no lo sabrán.

3. Importancia de la Documentación Continuada

Short description:

Entonces, la documentación incorrecta, espero que demuestre que es peor. La documentación puede hacer o deshacer un proyecto. La incorporación es realmente importante. El boca a boca es muy importante en nuestra industria. Si le preguntas a alguien, ¿qué biblioteca deberías usar? Y ellos dijeron, bueno, esta biblioteca es realmente ligera, realmente rápida. Oh, es terrible de usar. Me llevó horas o días configurarlo. Donde si alguien dijo, es un proyecto un poco grande, es un poco pesado, pero la documentación es genial. Puedes ponerte en marcha en minutos. Te garantizo que lo vas a probar, y probablemente terminarás usándolo durante mucho más tiempo. Entonces, el boca a boca es realmente, realmente importante.

Entonces, es una excelente manera de entrar en el código abierto. Este es un ejemplo realmente crudo, así que tómalo con un grano de sal. Pero tiene los dos pasos faltantes del último ejemplo, pero el último paso es incorrecto. Y en realidad he visto esto en un proyecto. Y es interesante ver lo que la gente intenta. Podrían poner sudo delante de él para ver si eso ayuda. Pero cuando buscan en Google ese cuarto comando, van a obtener ejecutar npm run build. Y entonces este comando va a funcionar. El problema es que no han resuelto el problema. Solo lo han hecho funcionar por ahora. Pero cuando hacen cambios de código en el entorno de desarrollo, esto no va a funcionar. No van a ver la recarga, y no van a ver sus cambios.

Entonces, la documentación incorrecta, espero que demuestre que es peor. Entonces, si la documentación es tan importante, ¿por qué no se le da tanta importancia como al código? La documentación puede hacer o deshacer un proyecto. He visto proyectos que han tenido éxito debido a una buena documentation. Y he visto proyectos realmente, realmente buenos que han fracasado debido a una mala documentation. La incorporación es realmente importante. Es la primera impresión que alguien tiene de tu proyecto. Es su primera experiencia. Y el boca a boca es muy importante en nuestra industria. Si le preguntas a alguien, sabes, ¿qué biblioteca deberías usar? Y ellos dijeron, bueno, esta biblioteca es realmente ligera, realmente rápida. Oh, es terrible de usar. Me llevó horas o días configurarlo. Probablemente no lo vas a probar, y mucho menos usarlo en tu proyecto. Donde si alguien dijo, es un proyecto un poco grande, es un poco pesado, pero la documentation es genial. Puedes ponerte en marcha en minutos. Te garantizo que lo vas a probar, y probablemente terminarás usándolo durante mucho más tiempo. Entonces, el boca a boca es realmente, realmente importante. Quiero decir, ¿has oído hablar de DX, Developer Experience? Supongo que sí. Perfecto.

4. Importancia de una Buena Documentación

Short description:

Y es real y existe. Así que quiero mostrar un último ejemplo del mundo real. La guía de inicio rápido en tu proyecto es realmente importante porque es la impresión que la gente va a tener de tu documentación completa. ¿Hay alguien aquí que quiera una mala documentación? Así que no queremos una mala documentación. La experiencia del desarrollador al escribir la documentación es mala. ¿Está en el mismo repositorio o tienes un flujo de trabajo separado? Si es doloroso hacerlo como desarrolladores, no lo vamos a hacer. La documentación escrita por el autor es solo un buen punto de partida. Puede ser revisada. La gente puede hacer preguntas, y podemos mejorarla. Nos olvidamos de incluir la documentación, incluso si está en un solo flujo de trabajo.

Y es real y existe. Así que quiero mostrar un último ejemplo del mundo real. Entonces, ¿cuál preferirías para entrar? Imaginemos que estás vestido de forma elegante y lista para venir a una conferencia increíble como React Day Berlin, y ambos coches se detienen. Ignora que el coche de la derecha es alemán. Sabes, no vamos a tener ningún sesgo hacia los increíbles coches alemanes, pero cuando el de la izquierda se detiene, vas a asumir que te vas a ensuciar al entrar, o que el interior probablemente esté sucio, mientras que el de la derecha, piensas que tiene aire acondicionado o asientos calefactados. Va a ser realmente agradable.

Y así, la guía de inicio rápido en tu proyecto es realmente importante porque es la impresión que la gente va a tener de tu documentación completa. Así que todos queremos buenos documentos. Y solo una última pregunta, ¿hay alguien aquí que quiera una mala documentación? Así que alguien levantó su teléfono para tomar una foto, pero pensé que estaban levantando la mano. Yo estaba como, no me lo esperaba. Vale, perfecto. Así que nadie quiere una buena documentación. Así que alguien quiere una mala documentación.

Así que no queremos una mala documentación. Y cuando digo nosotros, me incluyo en esto. ¿Por qué no escribimos una buena documentación? Creo que es porque la experiencia del desarrollador al escribir la documentación es mala. Así que si retrocedemos antes de tener una buena documentación, y necesitamos escribir una buena documentación, esa experiencia es realmente importante. Así que mencioné DX desde la perspectiva de consumir la documentación. Veámoslo desde el punto de vista de escribir la documentación. Creo que eso es aún más importante. ¿Está en el mismo repositorio o tienes un flujo de trabajo separado? ¿Está en una wiki separada donde tienes que enviar tu PR, se fusiona, y luego tienes que pensar en la documentación más tarde? Quiero decir, seamos realistas. Si es doloroso hacerlo como desarrolladores, no lo vamos a hacer. Quiero decir, por eso nuestras entradas de Jira nunca se actualizan. Tienes que iniciar sesión en otra plataforma, y sí, ya conoces la historia. Quiero decir, ¿usa Markdown, o usa un WYSIWYG de arrastrar y soltar u otra tecnología? Creo que esto es lo que necesitamos hacer en nuestros proyectos para hacerlo mucho mejor. Un solo flujo de trabajo donde una solicitud de extracción contiene documentos y pruebas, y además, seamos realistas, la documentación escrita por el autor es solo un buen punto de partida. Nunca va a ser la mejor documentación porque hacemos suposiciones, como vimos antes. Nos saltamos pasos, y por lo tanto, puede ser revisada. La gente puede hacer preguntas, y podemos mejorarla. Nos olvidamos de incluir la documentación, incluso si está en un solo flujo de trabajo.

5. Uso de MDX para Documentación

Short description:

Sé que lo hago, así que también tenemos como una casilla de verificación. ¿Sabes, he actualizado la documentación? Markdown es un lenguaje de marcado ligero. MDX es un superconjunto de Markdown y te permite escribir JSX dentro de tus archivos Markdown, lo cual es genial. MDX nos ayudó a lograr lo que necesitábamos. Tenía ese equilibrio. Podemos personalizar la salida de Markdown. También podemos reutilizar nuestros archivos Markdown en varios lugares. Incluso podemos reutilizar nuestros componentes del proyecto. Incluso es posible personalizar la documentación.

Sé que lo hago, así que también tenemos como una casilla de verificación. ¿Sabes, he actualizado la documentation? No es infalible, pero nos ayuda a recordar cuando creamos una solicitud de extracción para verificar y darle una marca, y si no le damos una marca, tal vez la persona que revisa también piense en verificar, bueno, tienes una documentation actualizada.

Tal vez deberías hacerlo con estos cambios de código. Markdown. Markdown es un lenguaje de marcado ligero. Todos ustedes lo saben. Estoy seguro de que lo usas todo el tiempo. Creo que es genial. Creo que es impresionante. Lo usamos en problemas de GitHub y comentarios y solicitudes de extracción. Todos amamos Markdown. La gente incluso escribe blogs con él, pero tiene sus límites. Aquí es donde entra MDX.

MDX es un superconjunto de Markdown y te permite escribir JSX dentro de tus archivos Markdown, lo cual es genial. Así que descubrí que MDX nos ayudó a lograr lo que necesitábamos. Tenía ese equilibrio. Podemos personalizar la salida de Markdown. Ya sabes, muchas bibliotecas hacen eso. Eso es genial. Es realmente fácil de usar, creo. También podemos reutilizar nuestros archivos Markdown en varios lugares. Así que puedes enlazar a una página separada, pero tal vez un pequeño fragmento de documentación Markdown documentation no requiere su propia página. Así que puedes importarlo e incluirlo en tus otros archivos Markdown, lo cual es impresionante. Incluso podemos reutilizar nuestros componentes del proyecto. Así que podemos hacer que se vea similar. Nuestra documentation se verá muy similar a nuestro proyecto real. Podemos recorrer los data de nuestro archivo de configuración, exponer los data de la sesión o las variables de entorno, esperemos que nada secreto. Pero entiendes la idea. Incluso es posible personalizar la documentation. Así que si alguna documentation está diciendo, no sé, necesitas llamar a este fragmento de código con tu ID de proyecto, puedes poner su ID de proyecto o cualquier ID en la documentation, lo cual creo que es súper, súper impresionante.

6. Uso Continuado de MDX para Documentación

Short description:

De nuevo, es esa experiencia de desarrollador. Vemos una imagen, código en línea, negrita, cursiva, citas. Podemos combinarlos. Así es como se verá, muy similar al resto de nuestro proyecto. Eddie, ¿qué pasa con Ascii Docs o Ascii Doctor? Me encantan esas herramientas. Es mucho para que el equipo aprenda. Es más difícil de integrar. Lo que se genera en el HTML es H2, H3 y una lista. Puedes agregar funcionalidad adicional. Este es un bloque de código.

De nuevo, es esa developer experience. Quiero decir, esto es Markdown con el que todos están familiarizados. Vemos una imagen, vemos código en línea, negrita, cursiva, citas. Quiero decir, todos están familiarizados con esto. Somos una conferencia de React, así que probablemente todos ustedes también están familiarizados con esto. Veo a algunas personas asintiendo.

Genial, no voy a repasarlo. Pero podemos combinarlos. Así que ahora tenemos los dos hashes, que es nuestro H2 en HTML, se convierte. Y luego tenemos nuestro componente de alerta de nuestro proyecto. No hemos hecho este componente de alerta específicamente para nuestra documentation. Esta es una alerta si obtenemos una presentación de formulario incorrecta o lo que sea. Entonces, y luego tenemos más Markdown. Así que es súper, súper consistente. Y así es como se verá. Y verás que es muy similar al resto de nuestro proyecto.

Sé lo que algunos de ustedes están pensando. Algunos de ustedes que han pasado un poco de tiempo en el mundo de la documentation estarán pensando, Eddie, ¿qué pasa con Ascii Docs o Ascii Doctor? Me encantan esas herramientas, por cierto. Son absolutamente impresionantes. Sin embargo, es mucho para que el equipo aprenda. Es todo otro tipo de marcado para aprender. Y tiene muchas funcionalidades. La gente escribe libros con él. Es genial. Pero el proceso de incorporación para el equipo es mucho más difícil. Y también encontré que es mucho más difícil integrarlo directamente en el proyecto también. Y de nuevo, solo para demostrártelo que lo que se genera en el HTML, la salida, es H2, H3 y una lista y así sucesivamente. Así que nada demasiado sofisticado. Así que quiero mencionar que no solo incluyendo componentes, pero puedes agregar funcionalidad adicional. Así que este es un bloque de código.

7. Uso de MDX para Documentación (Parte 2)

Short description:

MDX nos proporciona un equilibrio entre familiaridad y flexibilidad. Configurarlo es sencillo. Instala las dependencias de MDX, crea el archivo mdx-components.js, personaliza la salida HTML y configura Next.js para usar MDX. Plugins como remark y rehype permiten resaltar la sintaxis, numerar líneas e incrustar publicaciones sociales y gráficos.

Hemos usado nuestros triple backticks, quizás añadido JSON en la parte superior al final de los tres backticks para dar un resaltado de sintaxis. Pero, ¿qué notamos? Notamos en la parte superior derecha un botón de copia. Así que podemos agregar funcionalidad a nuestra documentation también. Así que siento que MDX nos da ese equilibrio entre lo que nos es familiar y también la flexibilidad.

Sé lo que estás pensando. ¿Qué tan difícil es configurarlo? Quiero probarlo hoy. Bueno, si te tomas un minuto de tu descanso para almorzar, podrías probar esto. Podrías crear un nuevo proyecto Next.js o podrías añadirlo a tu proyecto Next existente o proyecto React o cualquier otro proyecto. Realmente sencillo. Instalas las dependencias de MDX para la biblioteca o marco que estás utilizando. Y luego para el proyecto Next.js, necesitas en la raíz del proyecto, mdx-components.js. Y en este ejemplo, simplemente estamos devolviendo el HTML predeterminado que se genera a partir del markdown, y vamos a personalizar eso en breve. Y luego tenemos nuestra configuración de Next.js para usar con MDX. Mencioné sobre personalizarlo. Así que con ese archivo, ese componente que está en la raíz de tu proyecto, puedes ver aquí, hemos personalizado el H1 y la imagen. Y es realmente sencillo. Es una sintaxis con la que ya estás muy familiarizado. Este es un proyecto real. Así que la razón por la que te muestro esto es que a la izquierda, puedes ver el código para generar esta página a la derecha. Y si miras en la parte inferior a la izquierda, verás que tiene diseños. Así que ahora a la derecha, antes solo te estaba mostrando la salida real, pero puedes ver la página completa, en realidad tenemos navegación. Así que ahora, de nuevo, está incluido en nuestro proyecto. Se trata como código, y para el usuario, también parece parte del proyecto.

Vale. Así que plugins. Hay muchos plugins que puedes usar con MDX. Y a todos nos encantan los plugins, ¿verdad? Añadimos un montón de plugins a todos nuestros proyectos, como remark, rehype. ¿Qué hacen estas cosas? Hacen resaltado de sintaxis para tus bloques de código. Puedes hacer numeración de líneas. Puedes incrustar publicaciones sociales, gráficos.

8. Uso de Front Matter y Pruebas

Short description:

Puedes usar front matter y cargar contenido remoto. Las pruebas son una gran herramienta, pero no son perfectas. Ten pruebas para verificar la carga de la página y evitar errores. Trata la documentación como código.

Incluso puedes usar front matter. Eso es donde, para aquellos de ustedes que han usado Jekyll antes, puedes poner, como, la configuración YAML en la parte superior también. Quiero decir, incluso puedes cargar contenido remoto. Obviamente, necesitas ser un poco cuidadoso en términos de security, pero también puedes hacer eso.

Mencioné testing antes. Quiero tocarlo brevemente de nuevo. Algunos desafíos. Así que es una gran herramienta. Recomiendo encarecidamente su uso, pero no es perfecto. Nada lo es nunca. Asegúrate de tener pruebas que simplemente verifiquen que la página se carga en toda tu documentation. Solo verifica que el título aparece y no hay error. Encontré que a veces algunos plugins de VS Code, cuando guardas esos archivos, se confunden un poco. Podrías agregar tres back ticks extra. Hubo un error que tuve recientemente. No sé por qué, al final del archivo. Así que solo verifica que se carguen y no se rompan.

Entonces, al final, normalmente dices conclusión, conclusiones, etc. Para ser honesto, quiero decir que esto es el comienzo. Quizás es el comienzo del desarrollo dirigido por documentación, DDD. Vale. DDD ya ha sido tomado. Haremos una masterclass sobre eso. Trabajaremos en ello. Pero las documentaciones son realmente, realmente importantes. Y la developer experience de escribir documentation, creo que es aún más importante. Recomiendo mantener las documentaciones en el mismo repositorio. Ten solicitudes de extracción. Ten esos cambios de documentation también. Trata las documentaciones como código.

9. Comentarios Finales y Llamado a la Acción

Short description:

Recompensa la documentación al igual que el código. Desarrollo impulsado por documentación. Escribe primero la documentación. Conéctate conmigo en las redes sociales. Únete a mi entusiasmo geek. Gracias a todos por su participación.

Recompénsalo igual que el código. Amo las malas documentaciones. Nunca fue dicho por nadie. Así que nunca escucharás eso. No creo que nunca lo escuchemos. Desarrollo impulsado por documentación. ¿Por qué no escribir primero la documentación? Te dejaré con ese pensamiento.

Si alguno de ustedes quiere unirse a mi entusiasmo geek, por favor. Me encantan las preguntas. Hazme preguntas al final o después. Si quieres conectarte conmigo en las redes sociales, este es mi código QR de Biodrop. Puedes obtener mi YouTube, Twitter, Eddy Hub que también se mencionó antes. Estoy a tiempo completo en el proyecto open-source. Biodrops, ¿quieres unirte a mi entusiasmo geek? Sé que Julia me ayuda con accessibility y ha hecho algunas solicitudes de extracción increíbles. Así que muchas gracias, Julia, también. Pero sí, ven y únete a nuestro entusiasmo geek.

QnA

Contribuyendo a la Documentación de Código Abierto

Short description:

Gracias a todos por no quedarse dormidos. Mejorar la documentación es la mejor manera de entrar en el código abierto y acelerar tu carrera. Comienza corrigiendo errores tipográficos y utilizando tu nuevo par de ojos. Haz que la revisión de la documentación sea parte de tu flujo de trabajo al revisar las solicitudes de extracción.

Muchas gracias a todos por no quedarse dormidos. Gracias. Me encanta la documentation, y me encanta de lo que hablaste, especialmente al principio. Hiciste que todos levantaran las manos como, ¿a quién le gusta leer buenos documentos? ¡Yay! ¿A quién le gusta escribir documentos? Hay mucha gente. Todos saben que necesitamos buenos documentos. Pero a veces tal vez se encuentran trabajando en un proyecto de open-source o con un proyecto de open-source, se encuentran con alguna documentation que falta. Y la gente quiere mejorarla. Al menos yo he estado en esta posición antes, pero es intimidante saber que, como, ¿tengo la experiencia? ¿Voy a poner la documentation para que alguien más venga a derribarla y diga, no es suficientemente buena? Pero, ¿cómo pueden las personas entrar en eso, comenzar a contribuir a esos proyectos? Quiero decir, la mejor manera de entrar en open-source y de relacionarse con personas increíbles y acelerar tu career, como en la charla que tengo, es mejorar la documentation. Si eres nuevo en una tecnología o un proyecto, tienes una ventaja. Tienes un nuevo par de ojos. No vas a hacer suposiciones. Vas a pasar por ello paso a paso y comprobar si las cosas funcionan o están desactualizadas. Quiero decir, seamos honestos, mi primera contribución a open-source fue contribuir a la documentation. Corregí un error tipográfico. Y si somos realmente honestos, creo que todos somos amigos aquí, mi décima contribución también fue corregir un error tipográfico. Pero así es como todos empezamos. Así que lo recomiendo encarecidamente. Y como dije, tu nuevo par de ojos puede agregar mucho valor. Diré que he corregido el error tipográfico, pero recuerdo una vez que corregí el error tipográfico que estaba en inglés británico. Y luego se volvió a cambiar y yo estaba como, sí, me lo merezco. Me lo merezco. Eso fue al principio de mi career en open-source. Pero sí, vamos a saltar a algunas de las preguntas que han venido de la audiencia. Lo tienes ahí abajo si quieres leerlo también, que son, ¿cuáles son algunos de los tips para mantener la documentation actualizada? Eso es lo que hablaste, que es uno de los peores escenarios posibles, como la documentation que es incorrecta. Así que tal vez está desactualizada o algo así. Entonces, ¿cuáles son algunos tips para que la gente la mantenga actualizada? Veo en algunas de las preguntas, IA y demás, la IA consume nuestra documentation. Así que necesitamos mantenerla actualizada. Eso es realmente importante. Creo que los tips son hacerlo parte de tu flujo de trabajo cuando estás revisando las solicitudes de extracción. Creo que eso es realmente importante.

Importancia del Uso Responsable de la IA

Short description:

Deberíamos tratar la documentación como parte de nuestro flujo de trabajo y celebrar su importancia. Al usar herramientas como la IA, es importante usarlas de manera responsable y no depender completamente de ellas. Durante Hacktoberfest, se utilizó la IA para generar código y documentación, pero se debe revisar a fondo para verificar su precisión. La IA aún está en sus primeras etapas y debe usarse como una herramienta con participación humana.

Y necesitamos celebrar que la documentation esté actualizada y no sea una idea tardía. No hay herramientas mágicas. He probado varias cosas y están bien. Todavía están bajo revisión. Así que tal vez hablemos en unas pocas semanas o un mes. He tenido algunas personas que se han acercado recientemente y dicen, oh, ¿has probado esta herramienta? Así que la estoy explorando. No creo que haya una varita mágica que puedas agitar. Creo que solo necesita ser tratado al igual que nuestros cambios de código como parte de nuestro flujo de trabajo, y deberíamos celebrarlo con suerte también.

Por supuesto. Y sé que también tocaste este tema, porque creo que mucha gente, cuando quieren usar herramientas como la IA, quieren tener un fuego y olvidarse. Como, oh, lo he puesto y no necesito pensar en ello. Entonces, obviamente, esa no es la forma correcta. ¿Hay tal vez alguna forma en que las personas puedan usarlo, pero de una manera segura que no sea, que no sea irresponsable, diría yo.

Cierto. Yo diría, pruébalo. Durante Hacktoberfest en octubre, cuando la gente estaba contribuyendo al código abierto, la gente usaba mucho la IA para generar código, documentation, pero nunca lo revisaron realmente. Y creo que si simplemente revisaran la documentation que generaron y la leyeran, probaran los comandos, verían que tal vez faltaban algunos pasos o tal vez había una mezcla de versiones con la herramienta que estaban usando. Así que solo diría, revísalo y compruébalo. O podrías pedirle a un amigo que lo haga si no le importa. Sí, le pediría a un amigo. Creo que es solo tener eso, de nuevo, esa nueva perspectiva de otra persona. Pero si sigues haciéndolo todo el tiempo porque no lo estás revisando tú mismo, definitivamente lo revisaré yo mismo, luego obtendré una segunda opinión después. Sí, por supuesto. No creo que sea confiable todavía, así que tienes que esperar a que, y también es como un bebé, ¿verdad? No vas a decir, oh, has aprendido a caminar. Bien, corre 100 metros ahora. Vas a caminar, sostener la mano del bebé. Y creo que al menos ahora, la IA definitivamente está en ese espacio. Es una herramienta que puedes usar, pero todavía necesitas ser parte de ese proceso.

Bien, ahora esto es como entrar en tanta semántica y los diferentes enfoques para los documentos. Hay un versus.

Comentarios en línea vs Documentación

Short description:

Cuando se trata de comentarios en línea versus documentación, creo en usar ambos. Al copiar y pegar una frase o párrafo de la documentación y proporcionar un enlace, los desarrolladores pueden obtener una versión TLDR y elegir leer más si es necesario. Utilizando un enfoque de dieta equilibrada, deberíamos utilizar diferentes herramientas y formatos para la documentación. Por ejemplo, MDX es una herramienta poderosa que estoy emocionado de probar.

Estoy bastante seguro de que muchas de tus respuestas van a ser depende, pero vamos a entrar en ellas. Así que una de ellas es sobre comentarios en línea versus documentation. ¿Qué piensas al respecto? Permíteme aclarar. Así que comentarios en línea, estamos hablando de solicitudes de extracción y luego documentation. Estamos hablando de, qué, dirigir a alguien a la documentation y decir que esto se puede leer aquí. Si ese es el caso, y si no lo es, lo siento, me equivoqué. Ven y charla conmigo después y podemos profundizar un poco más.

Pero yo diría ambos. Y lo que quiero decir con eso es, copia y pega esa frase y un párrafo de la documentation y luego pon un enlace y simplemente di, si quieres leer más, ve y aquí está la documentation completa. Creo que como desarrolladores, todos amamos ese TLDR. Te garantizo que, probablemente no irán a leer la documentation completa a menos que estén atascados o realmente lo necesiten. Así que esa línea, creo que intentaremos reducir ese ida y vuelta. Quiero decir, para mis videos de YouTube, tuve a alguien que dijo, vi que tienes un video de YouTube de 10 minutos sobre esto. ¿Puedes resumirlo para mí en como dos líneas? Yo estaba como, ya es un resumen en un video de 10 minutos. Está editado muy rápidamente. Así que sí.

No, totalmente. Y creo que también hay una parte de eso, que es usar todas las diferentes herramientas también. No es uno u otro. Es una dieta equilibrada. Como quieres tener diferentes cosas en tu dieta y quieres tener una dieta equilibrada de documentation. Me encanta ese ejemplo. Di una charla llamada La Dieta Equilibrada de la Documentation. Orgulloso, orgulloso de ello. Muy bien. Así que sigamos. Y esto es más sobre MDX. Parece que me encanta. Nunca he usado MDX, pero se ve increíble y quiero probarlo. Y la pregunta de esta persona también es mi pregunta.

Soporte para MDX en GitHub y GitLab

Short description:

El soporte en términos de la comunidad es excelente, con muchos plugins disponibles. Sin embargo, cuando se trata de renderizar archivos MDX en GitHub y GitLab, los bloques de código no se ven muy bien. Sería mejor dirigir a los usuarios a las páginas de GitHub o a la aplicación desplegada para leer la documentación. GitHub está añadiendo continuamente más herramientas a su renderizado, por lo que sería bueno que añadieran soporte para MDX a la página de readme.

¿Cómo es el soporte para esto en GitHub o GitLab o donde la gente ya está usando Git? Así que el soporte, supongo, puede ser tomado de dos maneras. Así que daré dos respuestas. Así que el soporte en términos de la community, creo que es genial. No he tenido ningún problema. Como dije, hay muchos plugins. Y si he tenido problemas, he hecho una pregunta como, no recuerdo, creo que lo hice en Discord y alguien respondió. Pero en términos de soporte, en términos de, si pones, porque nuestros archivos MD se renderizan en GitHub y GitLab. MDX lo es y no lo es. Así que puedes ver los bloques de código. No se ve muy bien. Así que el soporte en términos de, no dirigiría a alguien a leer la documentation en GitHub en el archivo MDX. Sería como las páginas de GitHub o la aplicación desplegada o algo así. Aún no ha llegado tan lejos. Pero sé que GitHub siempre está añadiendo más herramientas a su renderizado. Así que tal vez deberíamos pedir a GitHub que añada como MDX justo en, léeme cuando llegues a la página. Eso sería bastante agradable en realidad.

Diferentes Preferencias de Documentación y Código

Short description:

Te encuentras con diferentes documentaciones, y hay algunas menciones honoríficas. La documentación de Next.js tiene ejemplos simples y complejos, excepto para el middleware. El equilibrio en la documentación es importante. El código legible y la gran documentación son subjetivos. Obtén retroalimentación de la comunidad para mejorar. Se elogia la documentación en BioDrop.

Muy bien. Y te encuentras con tantas diferentes documentation. Probablemente tengas algunas, como, no diré una, eres las mejores docs individuales, pero tal vez hay solo algunas menciones honoríficas que piensas que estas personas hacen esto realmente bien. Las personas hacen algo más realmente bien. Esa es una muy buena pregunta. Lo siento. Sí. Muy buena pregunta. Y me has puesto en el lugar. Esa es difícil. Diría que Next.js, su documentation, tienen algunos ejemplos simples. Si solo quieres empezar, algo que funcione, pero luego tienen como, si quieres algo más complicado, como toda la configuración, como los ejemplos de la vida real completamente desarrollados, aparte de su middleware, estaba haciendo algunas cosas de dominio personalizado en Vercel y Next.js y su middleware. Era como, no sé, 20 líneas de código. Y me tomó como tres semanas hacerlo funcionar. Y hice un video sobre eso porque estaba bastante frustrado. Como es en realidad, podrías codificar esto en unos 30 minutos, pero tanto vaivén. Así que aparte de esa área, porque no creo que muchas personas usen el middleware para subdominios para aplicaciones multi-tenant. Así que aparte de eso, el resto de la documentation es realmente buena. Necesitas equilibrio de documentation. Y también cuando ves una documentation en espera, la documentas también, para que otras personas puedan aprender de ella.

Muy bien, ahora esta es otra, supongo que va a ser una pregunta interpens, pero alguien ha preguntado como código legible con quizás buenos comentarios y otras cosas, pero no mucha documentation. ¿Prefieres eso sobre código complejo y gran documentation? Tengo una teoría. Creo que muchas personas diferentes dan diferentes respuestas a esto, dependiendo de su estilo, pero ¿cuál es tu respuesta? ¿Y qué recomendarías a los demás? Creo, sabes, el código legible es muy subjetivo. Creo que el código complejo y la gran documentation también es subjetivo. Diría que obtén retroalimentación de la community y puedes mejorarla, ¿verdad? Cuando envío una solicitud de pull o doy una masterclass, no estoy diciendo que esta es la solicitud de pull perfecta o la masterclass perfecta. Estoy allí para iniciar esa característica y tal vez sacar el MVP a los usuarios o iniciar la conversación en una masterclass. Seguimos iterando y mejorando. Si miras la documentation en BioDrop, la gente dice gran documentation. No es por mí. Yo lo inicié.

Valor de una Perspectiva Fresca y Orgullo de Biodrop

Short description:

Hay valor en que alguien nuevo en el código o proyecto proporcione una perspectiva fresca. Encontrar un equilibrio entre el código legible y una mejor documentación es importante. El orador está orgulloso del proyecto Biodrop y de la colaboración con la comunidad en la mejora de la documentación.

Probablemente hay como mil colaboradores en esos archivos. Y lo que digo a las personas en la community para mejorar eso, para tener el código legible, para tener una mejor documentation, cuando alguien es nuevo en el proyecto, ellos dicen, oh, ¿puedes contarme sobre el proyecto? ¿Cuéntame sobre la documentation? Quiero aprender más sobre eso. Y yo estoy como, no. ¿Puedes contarme sobre el proyecto y sobre el código? Y si no puedes, no hay nada malo contigo. Hay algo malo con nuestro proyecto. Pero con tu ayuda, con tu perspectiva fresca, podemos mejorarlo. Y así es como lo hemos iterado y lo hemos hecho mejor. Así que ahí es donde creo que el valor de alguien nuevo en el código o el proyecto puede realmente, realmente ayudar. Así que diría que encuentren un equilibrio. Es difícil. Quizás podamos discutir eso más después. Me interesaría conocer algunos ejemplos.

No, seguro, seguro. Sé que hay muchas más preguntas que el tiempo que tenemos. Así que si no llegamos a tu pregunta, recuerda venir a buscarlo y podrás hacer tus preguntas en persona. Y una pregunta que quiero hacer es una de las preguntas que teníamos antes, pero quiero reformularla. ¿Qué documentation, esta será la última, de qué documentation estás más orgulloso en la que has trabajado que estás más orgulloso y por qué? Me encanta esta pregunta. Y diría Biodrop porque esto es como, creo que mi 200º proyecto de open-source, pero es el único donde he tenido personas en tecnología, sabes, revisar la documentación, mejorarla. Y también personas que no están en tecnología, diseñadores, abogados, otras personas revisan la documentation. Así que creo, de nuevo, no es perfecto. Todavía hay espacio para mejorar, especialmente a medida que el código ha avanzado y así sucesivamente. Pero creo que tenemos una muy buena base. Así que estoy realmente orgulloso de lo que los mantenedores y la community han hecho por el proyecto Biodrop. Y en verdadero estilo de community, no está orgulloso porque lo hizo él, sino porque tantas otras personas trabajaron con él en el viaje. Gracias por permitirnos ser parte de tu viaje, Eddie. Muchas gracias. Gracias. Realmente lo aprecio. Gracias a todos.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

JSNation 2022JSNation 2022
28 min
Full Stack Documentation
Interactive web-based tutorials have become a staple of front end frameworks, and it's easy to see why — developers love being able to try out new tools without the hassle of installing packages or cloning repos.But in the age of full stack meta-frameworks like Next, Remix and SvelteKit, these tutorials only go so far. In this talk, we'll look at how we on the Svelte team are using cutting edge web technology to rethink how we teach each other the tools of our trade.
React Summit US 2023React Summit US 2023
32 min
Gateway to React: The React.dev Story
A behind the scenes look at the design and development of the all-new React docs at react.dev. The new react.dev launched this year introducing new methodologies like challenges and interactive sandboxes and subtle inclusivity features, like "international tone" and culturally agnostic examples. Not only have the new docs changed how people learn React, they've inspired how we think about developer education as a community. In this talk, you will learn how the React team and some ambitious community members made the "React docs rock" for a generation of front end developers and how these new patterns and established techniques can be applied in your favorite projects.
React Finland 2021React Finland 2021
27 min
Opensource Documentation—Tales from React and React Native
Documentation is often your community's first point of contact with your project and their daily companion at work. So why is documentation the last thing that gets done, and how can we do it better? This talk shares how important documentation is for React and React Native and how you can invest in or contribute to making your favourite project's docs to build a thriving community
React Finland 2021React Finland 2021
18 min
Documenting components with stories
Most documentation systems focus on text content of one form or another: WYSIWYG editors, markdown, code comments, and so forth. Storybook, the industry-standard component workshop, takes a very different approach, focusing instead on component examples, or stories.
In this demo, I will introduce an open format called Component Story Format (CSF).
I will show how CSF can be used used to create interactive docs in Storybook, including auto-generated DocsPage and freeform MDX documentation. Storybook Docs is a convenient way to build a living production design system.
I will then show how CSF stories can be used create novel forms of documentation, such as multiplayer collaborative docs, interactive design prototypes, and even behavioral documentation via tests.
Finally, I will present the current status and outline a roadmap of improvements that are on their way in the coming months.
TypeScript Congress 2022TypeScript Congress 2022
25 min
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
Using real-life open-source examples, we'll explore the power of TypeScript to improve your users' experience. We'll cover best practices for library authors, as well as tips and tricks for how to take a library to the next level. This talk will cover: 
- how to leverage the type inference to provide help to your users; - using types to reduce the need and complexity of your documentation - for example, using function overloads, string literal types, and helper (no-op) functions; - setting up testing to ensure your library works (and your types do too!) with tools like tsd and expect-type; - treating types as an API and reducing breaking changes whilst shipping enhancements; - I'd draw on my experience with libraries like nuxt3, sanity-typed-queries and typed-vuex and show what we managed to do and what I'd do differently in future. 

React Advanced Conference 2021React Advanced Conference 2021
24 min
The Legendary Fountain of Truth: Componentize Your Documentation!
"In Space, No One Can Hear You Scream." The same goes for your super-brand-new-revolutionary project: Documentation is the key to get people speaking about it.Building well-fitted documentation can be tricky. Having it updated each time you release a new feature had to be a challenging part of your adventure. We tried many things to prevent the gap between doc and code: code-generated documentation, live examples a-la-Storybook, REPL...It's time for a new era of documentation where people-oriented content lives along with code examples: this talk will guide you from Documentation Best Practices – covered from years of FOSS collaborative documentation – to the new fancy world of Components in Markdown: MDX, MDJS, MD Vite, and all.Let's build shiny documentation for brilliant people!