Documentación de la biblioteca de componentes inclusiva y sin problemas

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.

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.

De esta manera, todo el sitio reconocería el contenido de MDX. Sin embargo, tuvimos que hacer una cosa adicional para nuestra plantilla de página de documentación de componentes. Dado que nuestros archivos de MDX de componentes estaban ubicados fuera del directorio fuente, se necesitaba el renderizador de MDX para envolver el contenido de nuestra plantilla de página de componente. De lo contrario, los archivos de MDX se representarían así en el navegador.

Ahora que nuestra plantilla de diseño utilizaba el renderizador de MDX, nuestras páginas de componentes de MDX se representarían como queremos en el navegador. Ahora podíamos agregar componentes de React junto a bloques de código en nuestro MDX, y se representarían sin problemas. Incluso podíamos envolver un componente de botón con un componente de cuadro de visualización y agregar una apariencia más cohesiva a la combinación de bloques de código de componentes. Si queríamos agregar una tabla de props para mostrar qué props se pueden usar con un componente y creamos un componente que obtuviera datos para representar como una tabla de props, simplemente agregábamos ese componente al archivo MDX de documentación y, ¡voilà!, la documentación mostraría una tabla de props.

Para nuestras recomendaciones de hacer y no hacer con los componentes, solíamos tener que escribir una lista desordenada en el archivo de Markdown y los enlaces y la lista se representaban así. Con el soporte de MDX, en su lugar creamos un componente personalizado que se representa en listas ordenadas. Podíamos pasar una lista de cosas que hacer y una lista de cosas que no hacer a ese componente y, ¡boom!, una lista de recomendaciones bien estilizada. Bloques de código. Markdown tiene un gran soporte para bloques de código. MDX hace que sean aún más poderosos. Así que estábamos emocionados de agregar esta función. Puedes anular el estilo de un bloque de código en un archivo de MDX con un bloque de código personalizado o incluso mostrar diferentes tipos de bloques de código. Puedes usar el renderizador Prism de React en un componente de bloque de código personalizado e importar un tema con buen contraste de colores, como el tema night owl de Sarah Drasner. Luego puedes envolver tu bloque de código y darle estilo. Importa ese componente de bloque de código en tu elemento raíz de envoltura junto con la utilidad de bloque predecodificado y anula el estilo predeterminado de la etiqueta pre a nivel de aplicación pasándolo como un componente al elemento raíz de envoltura. Así que ahora, cuando escribas un bloque de código en MDX, en lugar del estilo base, el bloque de código personalizado se representará con resaltado de sintaxis. Un dato curioso, puedes pasar una propiedad a ese bloque de código y hacer cosas realmente geniales si usas bloques de código personalizados. Por ejemplo, si abstraes esto en un patrón más seco en nuestro componente de bloque de código personalizado y pasas la propiedad de cuadro de visualización a ese bloque de código, si agregas la propiedad de cuadro de visualización al bloque de código en MDX, obtendrás un cuadro de visualización junto con un bloque de código. Ahora, ¿qué pasa si quieres que tu bloque de código sea editable? Puedes agregar una opción de React live al componente y mostrar el componente dentro de un par de cuadro de visualización con un bloque de código editable. Así que si agregas la propiedad de React live a tu bloque de código de MDX, obtendrás un bloque de código editable y verás tus cambios en tiempo real. Así que si escribimos algo como esto, donde tenemos tres bloques de código en MDX, uno con la propiedad de React live, otro sin propiedad solo el nombre del lenguaje y el tercero con la propiedad de cuadro de visualización pasada. Esto es lo que verás. Aquí está, he creado rápidamente un archivo de MDX en mi sitio de blog para demostrar si pasas esto, este es el JSX con la propiedad de React live pasada. Este es solo JSX pasado como código. Y este es pasando la propiedad de cuadro de visualización al bloque de código JSX. Lo genial del que tiene la propiedad de React live es que estamos combinando bien la elegancia del cuadro de visualización y el bloque aquí, pero esto ahora es editable.

Así que puedo hacer cosas con él. Y si sé qué props admite mi componente, podría hacer este botón. Si ves, mira allí, en realidad tiene manejo de errores, pero botón pequeño, wow. Y también podría, quiero, sé que admito iconos, así que el icono que podría usar es la flecha derecha porque estoy usando componentes React de Font Awesome bajo el capó. Mira eso, acabo de agregar un icono a mi botón. Pero esto, agregar este tipo de bloque editable, soporte editable de React Live a tus bloques de código es muy poderoso porque tus desarrolladores podrán ingresar a tu componente, a tu documentación y jugar con las propiedades allí mismo y comprender cómo usar tu componente de inmediato en lugar de tener que intentar, ya sabes, buscar en todas tus tablas de props. Esta es otra forma para los aprendices que necesitan escribir cosas para ver cómo se rompen las cosas. Entonces, el componente de bloque editable, los bloques de código editables son increíbles. Ahora, voy a volver a las diapositivas y concluir esto. Concluir esto. Entonces, para concluir, si tu configuración de documentación es frágil, tus colaboradores huirán pero Gatsby y MDX ayudan a que tus documentos sean inclusivamente fluidos tanto en la configuración como en la ejecución. Entonces tus colaboradores volverán y estarán felices de ser parte de tu equipo. Gracias. ♪♪♪