¿Es su configuración de documentación compleja una pesadilla de mantenimiento y ahuyenta a posibles colaboradores? En esta charla, aprenderá cómo hacer que la documentación de su biblioteca de componentes React sea más amigable para los usuarios y colaboradores con Gatsby y MDX. Combine esto con las mejores prácticas de accesibilidad y su documentación será inclusivamente fluida.
Documentación de la biblioteca de componentes inclusiva y sin problemas
FAQ
Gatsby es una plataforma que permite crear sitios web optimizados, y se utiliza para mejorar la documentación de componentes al permitir la integración de MDX, lo cual facilita la inclusión de Markdown y componentes React directamente en los archivos de documentación.
MDX es una extensión de Markdown que admite la inclusión de JSX y componentes React. Permite una mejor presentación y accesibilidad en la documentación, al compilar en HTML semántico que mejora la experiencia de los usuarios con asistencia tecnológica.
Antes de Gatsby y MDX, la documentación del sistema de diseño era complicada con múltiples repositorios y pasos, y los scripts requerían un formato muy específico de Markdown que complicaba la inclusión de contenido variado y era poco amigable para nuevos colaboradores.
Gatsby simplificó el proceso de contribución al combinar los repositorios en uno solo y reducir los comandos necesarios. También permitió una configuración inicial fácil y la ampliación según las necesidades, mejorando así la estructura y accesibilidad de la documentación.
Con MDX, se facilitó la integración de componentes de React y bloques de código en la documentación. Esto incluyó tablas de propiedades, listas ordenadas personalizadas para recomendaciones de componentes y la posibilidad de hacer bloques de código editables para una interacción más dinámica.
Se utilizaron plugins como Gatsby-plugin-post-css, Gatsby-plugin-compile-es6, Gatsby-plugin-mdx, entre otros, para soportar estilos CSS, reconocimiento de archivos MDX y crear enlaces automáticos en los encabezados, mejorando la accesibilidad y la estructura del sitio.
Video Summary and Transcription
Esta charla discute cómo Gatsby y MDX pueden mejorar la documentación de la biblioteca de componentes. El orador comparte su experiencia con un sistema de diseño anterior y los desafíos que enfrentaron con la documentación. Explican cómo se eligió Gatsby como solución y los beneficios que proporcionó. Se destaca el uso de MDX como una forma de mejorar la documentación de los componentes. También se menciona la adición de bloques de código editables como un medio para hacer que la documentación sea más interactiva e intuitiva.
1. Introducción a la Documentación de la Biblioteca de Componentes
Hola, mi nombre es Kathleen McMahon y hoy estoy aquí para contarles cómo Gatsby y MDX hacen que la documentación de su biblioteca de componentes sea inclusiva y fluida. Antes de comenzar, aclaremos algunos detalles. Mi presentación de diapositivas se publicará en Noticed, incluyendo enlaces a los recursos que mencionaré brevemente. Antes de adentrarnos en Gatsby y MDX, retrocedamos un poco para que pueda presentarme un poco mejor. Soy ingeniera principal en CarGurus y corro en bicicleta, muy mal. Antes de CarGurus, fui líder técnica del Sistema de Diseño de O'Reilly Media. En nuestro caso, nuestro enfoque era extraer la lógica empresarial de nuestros componentes y garantizar la accesibilidad. Arreglamos nuestros colores, nuestros componentes, nuestros patrones y reiniciamos nuestra documentación. Una vez hecho esto, nos dimos cuenta de que parte de nuestro sistema estaba obstaculizando a nuestro equipo y siendo una barrera de entrada para nuestros colaboradores: nuestra documentación. Nuestro proceso se distribuía en dos proyectos, el repositorio del sistema de diseño y el repositorio de documentación del sistema de diseño. Simplemente comenzar a trabajar con estos repositorios era abrumador para los nuevos colaboradores, por decir lo menos. Los scripts estaban configurados de tal manera que tenías que escribir tu markdown en un orden muy específico para que tu componente y tu contenido se mostraran en la documentación. Entonces, aunque nuestros scripts de documentación eran excelentes para generar muestras de colores y detalles sobre qué props estaban disponibles en los componentes, el proceso no era bueno para crear nuestra documentación de componentes, lo cual frustraba a todos. Un error y, si no, se perderían fragmentos enteros de documentación de las páginas de los componentes. Teníamos la libertad de usar markdown, pero no estábamos aprovechándolo.
Cómo desarrollar tu aplicación web. Conéctate con otros desarrolladores web. Cómo desarrollar tu aplicación web. Crea un sitio web. Cómo crear un sitio web. Cómo crear un sitio web. Cómo crear un sitio web. Crea un sitio web. Cómo crear un sitio web. Cómo crear un sitio web. Cómo crear un sitio web. Cómo crear un sitio web.
Hola, mi nombre es Kathleen McMahon y hoy estoy aquí para contarles cómo Gatsby y MDX hacen que la documentación de su biblioteca de componentes sea inclusiva y fluida. Antes de comenzar, aclaremos algunos detalles. Mi presentación de diapositivas se publicará en Noticed, incluyendo enlaces a los recursos que mencionaré brevemente. La URL completa estará disponible más tarde hoy en Twitter. Pero por ahora, si quieres descargarla, si quieres echarle un vistazo, puedes visitar https://noti.st/r-e-s-o-u-r-c-e-1-1. También puedes encontrarme en resource11 en Twitter, Instagram y GitHub.
Antes de adentrarnos en Gatsby y MDX, retrocedamos un poco para que pueda presentarme un poco mejor. Soy ingeniera principal en CarGurus y corro en bicicleta, muy mal. Mayormente me verás disfrazada corriendo dos vueltas mientras tú corres seis, en la parte trasera del pelotón, en una bicicleta de una sola velocidad, a menos que suceda algo, como una pandemia que nos cierre las puertas. Entonces, tu temporada de carreras se pospone. Así que, aunque soy ingeniera y una ciclista muy lenta, soy una gran fanática de los sistemas de diseño, especialmente de las partes de la biblioteca de componentes. Antes de CarGurus, fui líder técnica del Sistema de Diseño de O'Reilly Media. Mientras estuve allí, aprendí mucho sobre optimizar las bibliotecas de componentes y la documentación. Si nunca has trabajado en un sistema de diseño antes, digamos que hay muchas partes móviles. Y si tu equipo principal es pequeño y estás reiniciando tu biblioteca de componentes, realmente tienes que elegir en qué enfocarte y confiar en tus colaboradores. En nuestro caso, nuestro enfoque era extraer la lógica empresarial de nuestros componentes y garantizar la accesibilidad. Arreglamos nuestros colores, nuestros componentes, nuestros patrones y reiniciamos nuestra documentación. Una vez hecho esto, nos dimos cuenta de que parte de nuestro sistema estaba obstaculizando a nuestro equipo y siendo una barrera de entrada para nuestros colaboradores: nuestra documentación. Nuestro proceso se distribuía en dos proyectos, el repositorio del sistema de diseño y el repositorio de documentación del sistema de diseño. En el repositorio del sistema de diseño, el contenido de la documentación se almacenaba en dos ubicaciones, mientras que el repositorio de documentación contenía el andamiaje del sitio y los componentes de diseño de la documentación. Para comenzar y ponerse en marcha, tenías que seguir una serie detallada de pasos para sincronizar, ejecutar scripts, obtener archivos, analizar información, generar datos y renderizar la documentación en una aplicación React. ¡Uf, eso es mucho! Simplemente comenzar a trabajar con estos repositorios era abrumador para los nuevos colaboradores, por decir lo menos. Pero espera, hay más. Los scripts estaban configurados de tal manera que tenías que escribir tu markdown en un orden muy específico para que tu componente y tu contenido se mostraran en la documentación. Tu encabezado de botón podía ir acompañado de un párrafo introductorio, pero solo un párrafo. Lo mismo con las variantes, solo un párrafo y luego un bloque de código. Las mejores prácticas debían escribirse como una lista desordenada, siempre, al igual que la sección de componentes relacionados, siempre y una lista ordenada. Entonces, aunque nuestros scripts de documentación eran excelentes para generar muestras de colores y detalles sobre qué props estaban disponibles en los componentes, el proceso no era bueno para crear nuestra documentación de componentes, lo cual frustraba a todos. Un error y, si no, se perderían fragmentos enteros de documentación de las páginas de los componentes. Teníamos la libertad de usar markdown, pero no estábamos aprovechándolo.
2. Mejorando el Proceso de Documentación con Gatsby
Esto fue un gran desafío cognitivo incluso para alguien que estaba muy familiarizado con el código base. Decidimos revisar nuestro proceso y ver qué no estaba funcionando. Uno de nuestros mayores problemas fue que elegimos mostrar una variante de componente a la vez en lugar de todas a la vez. Esto obligaba a nuestros usuarios a acceder repetidamente a un menú desplegable para comparar las variantes de componentes, lo que aumentaba el tiempo que necesitaban para buscar información. No tenía sentido. Así que decidimos que era hora de hacer que nuestro proceso de contribución a la documentación fuera más amigable para el usuario en términos de estructura y de cómo lo escribimos. Consideramos nuestras opciones para mejorar nuestra documentación y decidimos utilizar Gatsby por varias razones. Primero, Gatsby nos permitió migrar todas nuestras páginas principales de documentación directamente al sitio sin complicaciones. Segundo, Gatsby proporciona una configuración de webpack y Babel similar a Create React App, por lo que pudimos comenzar con un proyecto preconfigurado y ampliarlo según fuera necesario. Y tercero, Gatsby admite MDX, lo que nos permitió escribir la documentación de componentes utilizando Markdown, importar componentes de React directamente en el archivo y funcionar aún mejor. MDX se compila en HTML semántico, lo que a su vez mejora la accesibilidad del sitio. Como ventaja adicional, Gatsby nos permitió combinar nuestros repositorios en uno solo y reducir drásticamente la cantidad de comandos de CLI. Sin embargo, tuvimos que hacer algunos ajustes para que Gatsby se adaptara a nuestras necesidades.
Esto fue un gran desafío cognitivo incluso para alguien que estaba muy familiarizado con el código base. Ahora imagina si tienes un nuevo colaborador en tu proyecto, no sería precisamente una experiencia acogedora.
Decidimos revisar nuestro proceso y ver qué no estaba funcionando. Uno de nuestros mayores problemas fue que elegimos mostrar una variante de componente a la vez en lugar de todas a la vez. Esto obligaba a nuestros usuarios a acceder repetidamente a un menú desplegable para comparar las variantes de componentes, lo que aumentaba el tiempo que necesitaban para buscar información. No tenía sentido. En retrospectiva, esa decisión fue tan cuestionable como una receta que combina gelatina con mariscos.
Así que decidimos que era hora de hacer que nuestro proceso de contribución a la documentación fuera más amigable para el usuario en términos de estructura y de cómo lo escribimos. Especialmente las páginas de ejemplos de componentes. Queríamos que los usuarios tuvieran la confianza de que cualquier contenido que escribieran en la página de documentación se mostraría en esa página de documentación. Si hacíamos que nuestra documentación fuera más amigable para el usuario, tendríamos más colaboradores en lugar de menos.
Consideramos nuestras opciones para mejorar nuestra documentación y decidimos utilizar Gatsby por varias razones. Primero, Gatsby nos permitió migrar todas nuestras páginas principales de documentación directamente al sitio sin complicaciones. Segundo, Gatsby proporciona una configuración de webpack y Babel similar a Create React App, por lo que pudimos comenzar con un proyecto preconfigurado y ampliarlo según fuera necesario. Y tercero, Gatsby admite MDX, lo que nos permitió escribir la documentación de componentes utilizando Markdown, importar componentes de React directamente en el archivo y funcionar aún mejor. MDX se compila en HTML semántico, lo que a su vez mejora la accesibilidad del sitio. Mejor soporte para usuarios que dependen de tecnología de asistencia para acceder a la documentación. Si un sistema de diseño promueve la inclusión en general, y realmente debería hacerlo, tiene sentido que la documentación también sea inclusiva.
Como ventaja adicional, Gatsby nos permitió combinar nuestros repositorios en uno solo y reducir drásticamente la cantidad de comandos de CLI. La configuración predeterminada de Gatsby es excelente. Sin embargo, tuvimos que hacer algunos ajustes para que Gatsby se adaptara a nuestras necesidades. En el archivo gatsby-config, agregamos Gatsby-plugin-post-css para admitir post-css. Gatsby-plugin-compile-es6 para admitir nuestro paquete del sistema de diseño. Gatsby-plugin-mdx para que el sitio reconociera archivos MDX. Gatsby-remark-autolink-headers para generar enlaces automáticos para los encabezados de las páginas, lo que mejora el soporte para lectores de pantalla y teclado. Gatsby-plugin-page-creator para crear páginas a partir de la carpeta de páginas fuente. Y Gatsby-plugin-filesystem para poder importar nuestro archivo de datos y señalar a Gatsby la carpeta donde se encontraban todos nuestros archivos de componentes MDX. En el archivo Gatsby-node, agregamos una consulta GraphQL para encontrar el contenido de los componentes MDX y crear acciones de ruta y páginas para la documentación de los componentes. En el archivo Gatsby-browser, agregamos cosas que queríamos aplicar en todo el sitio, como nuestros estilos CSS globales y el componente wrap-root-element. El componente wrap-root-element actúa como un envoltorio alrededor del elemento raíz del sitio e importa el proveedor MDX.
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
Comments