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

Rate this content
Bookmark

¿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.

18 min
17 Jun, 2021

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.

Available in English

1. Introducción a la Documentación de la Biblioteca de Componentes

Short description:

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

Short description:

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.

3. Mejorando la Documentación de Componentes con MDX

Short description:

Se necesitaba el renderizador de MDX para envolver el contenido de nuestra plantilla de página de componente, asegurando una representación adecuada en el navegador. Ahora se pueden agregar fácilmente componentes de React a los archivos de MDX, lo que permite una representación fluida. Se pueden crear componentes personalizados para listas ordenadas, proporcionando una lista de recomendaciones bien estilizada. MDX también mejora el soporte de bloques de código, permitiendo estilos personalizados y diferentes tipos de bloques de código. Al agregar la propiedad React live, los bloques de código se pueden editar y los cambios se pueden ver en tiempo real.

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.

4. Mejorando la Documentación con Bloques de Código Editables

Short description:

Al agregar soporte editable de React Live a los bloques de código, los desarrolladores pueden jugar fácilmente con las propiedades del componente en la documentación. Esto proporciona una forma más interactiva e intuitiva de comprender cómo usar el componente. También permite a los aprendices experimentar y ver cómo diferentes entradas afectan el comportamiento del componente.

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. ♪♪♪

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
Top Content
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.