La Fuente Legendaria de la Verdad: Componentiza tu Documentación!

¡Hola a todos! ¡Qué bueno tenerlos aquí! Bienvenidos a esta sesión sobre documentación en una era dirigida por comandos. Así que vamos a hablar sobre la documentación como clave del éxito de tu proyecto. Quiero decir, sin importar si estás trabajando en una biblioteca, un componente individual, un sistema de diseño completo o una interfaz final de una aplicación, tu documentación es la clave del éxito de tu proyecto. Porque sin una documentación adecuada, nadie tendrá ni idea de cómo funciona y cómo se supone que debes usar tu proyecto o cualquier parte de tu proyecto. Así que debes mantener tu documentación correctamente asociada con tu código. De hecho, tener una documentación viva es un dolor hoy en día, simplemente porque si tienes que duplicar tu código de tu base de código a tu documentación, obviamente lleva a una desincronización en algún punto de tu documentación en comparación con tu base de código. Así que debes mantenerlos sincronizados si quieres estar listo para simplemente usar y mantener tu documentación a lo largo del tiempo, para tener tu proyecto listo para ser utilizado por cualquier persona en el pasado y en el futuro. Así que hemos intentado muchas cosas para mantener las cosas organizadas entre tu documentación y tu base de código. Hemos intentado cosas como storybook, hemos intentado cosas como incrustar, erpl en tu documentación en sí misma, hemos intentado muchas cosas pero la verdad real es que necesitamos una única fuente de verdad y esta única fuente es tu base de código en sí misma. No tu documentación, no tus ejemplos que estarán desactualizados en algún momento. Necesitas algo que sea definitivamente el único punto donde todo se origina y esto está directamente en tu base de código. Así que tenemos que hacer algo para mantener la documentación sincronizada con la base de código.

Y cuando divides toda tu interfaz frontend en componentes solamente, entonces puedes trabajar en partes pequeñas que están aisladas en tu aplicación. Y puedes extraer tu contenido y hacerlo funcionar de forma aislada en un entorno de prueba. Y en este entorno de prueba, tu componente se puede mantener, probar y documentar fácilmente. Y esta es la parte que estamos buscando en este momento. Entonces, en este marco de datos Axis, con una era de desarrollo impulsada por componentes, ¿cómo podemos combinarlos para aprovechar al máximo los dos mundos? Esto es realmente interesante, porque cuando trabajas de esta manera, es muy fácil extraer tu componente de tu aplicación y ponerlo en un entorno de prueba dedicado, trabajar en él, realizar algunas pruebas, utilizar este nuevo componente en vivo y tenerlo disponible para incrustarlo en diferentes partes, diferentes áreas de tu documentación. Así que tu documentación ahora puede ser completamente exhaustiva sobre cómo funciona de esta manera, cómo es este componente realmente útil, cómo podemos confiar realmente en este componente en este contexto particular, y así sucesivamente.

Entonces, en mi marco de datos Axis, poner algunas cosas dedicadas a mi componente en las guías o los README y los O2s, etc., es realmente muy útil porque ahora es fácil entender dónde puedo poner mi documentación para estas partes particulares de mis aplicaciones, que son este componente, mi menú desplegable, mi vista de galería, mi héroe, mi botón. Esto es exactamente cómo quiero realizar mi documentación, porque cuando busco una nueva documentación en un proyecto, lo que busco es: OK, ¿cuáles son los diferentes componentes disponibles en mi biblioteca, cómo puedo usarlos, cómo puedo hacerlos todos, cómo puedo conectarlos todos para interactuar entre mis componentes. ¿Cómo puedo usarlos en React, en Visual Effects, en lo que sea que quieras. Así es exactamente cómo tenemos que cambiar nuestra forma de pensar para colocar la documentación relacionada con un componente en las partes correctas de nuestra documentación general en su totalidad.

Entonces, con eso, ahora podemos jugar con los documentos en vivo porque podemos incrustar nuestro componente que probablemente está aislado de nuestra aplicación final en nuestra documentación a mano. Así que ahora es muy fácil simplemente jugar con nuestro componente en un entorno de prueba con este documento, este componente en nuestra documentación, jugar con él y probarlo, tener alguna especie de experimento, romperlo en algún momento. Pero esto es solo porque puedes usar tu componente en un área dedicada que está en vivo en la documentación. Entonces, necesitamos mezclar este componente en nuestra documentación, importarlo en nuestra documentación y tenerlo en vivo aquí. Entonces, ¿cómo podemos hacer eso ahora mismo? Esta es la respuesta que nos brinda el entorno MDX. Entonces, MDX es Markdown pero un Markdown glorificado.

Entonces, al escribir tus documentos, probablemente estés usando Markdown para escribir tu documentación. Esto es solo azúcar sintáctica en HTML, probablemente conozcas Markdown porque está en todas partes en este momento, desde GitHub hasta cualquier CMS o plataforma de documentación o plataformas de producción de documentos, por lo que es una sintaxis realmente simple, fácil de leer, fácil de contribuir, incluso si no eres técnico en absoluto. Porque esto es simplemente escribir texto con algún tipo de marcado que son solo caracteres simples, por lo que no es tan complejo. Es compatible con cualquier editor de texto, es muy fácil de usar, pero es demasiado simple para usar con documentos realmente complejos. Quiero decir, con Markdown no puedo incrustar mi componente en él, así que tengo que hacer algunas cosas. OK, puedo incrustar HTML directamente en mi Markdown, pero no es suficiente. Necesito algo más avanzado, y necesito algo más útil cuando quiero trabajar con él. Por eso ahora tenemos la sintaxis MDX, y el MDX es simplemente JSX incrustado en Markdown. O más que eso, esto es Markdown convertido a JSX, que ahora se convierte en HTML. Entonces, esto es un paso más entre el Markdown y el HTML en el proceso de renderizado. Esto no es solo una conversión lineal de Markdown a HTML, sino de Markdown a JSX a HTML. Entonces, en este entorno, cuando estoy trabajando en mi Markdown, en realidad estoy trabajando en un documento JS o más bien un documento JSX.

Así que puedo importar, exportar cualquier tipo de documento en él. Podría escribir Markdown en él, pero también podría colocar mi documento, mi componente en mi documento en este momento al final. Y esto ahora está incrustado en mi Markdown. Y esto se renderiza en mi Markdown, en el proceso final. Así que esto es realmente útil porque ahora tenemos componentes en Markdown directamente.

Bajo el capó, esto es solo el nivel estándar de Markdown con la sintaxis nativa de JSX todo mezclado. Podríamos incrustar componentes externos. Podríamos incrustar la representación de funciones y la representación de funciones externas. Podríamos pasar props. Podríamos contar con soporte nativo de TypeScript. Podríamos tener todo lo que estamos acostumbrados a hacer con JSX pero directamente en nuestro Markdown. Porque en el paso final, esto es solo un proceso de renderizado donde tengo una sintaxis de Markdown, una sintaxis de MDX, luego esto se convierte en un AST. Este es un AST de JSX. Luego, este AST de JSX se convierte en un AST de HTML. Luego, este AST de HTML se convierte en HTML. Esto es solo un proceso de conversión diferente. Esto es exactamente lo que estamos buscando. Ahora tenemos una sintaxis de Markdown lo suficientemente flexible como para ser utilizada para incrustar cualquier tipo de componente.

Tengo un diseño simple de MDX. Puedo incrustar cualquier prop en él, cualquier componente en él y puedo renderizar cualquier cosa que desee. Esa es una sintaxis JSX regular o una sintaxis de Markdown regular y las mezclo todas. Ahora tenemos diferentes entornos listos para incrustar el MDX. MDX es realmente simple. Solo hay que agregar una línea de configuración en tu configuración de Webpack o tu configuración de relab. Esto es realmente fácil de hacer. No es una configuración compleja de tener. Pero ahora dividimos este entorno en dos mundos. Tenemos por un lado las herramientas básicas que están listas para incrustar el MDX. Puedo hacer MDX con cualquier tipo de generador estático, desde Gatsby hasta ReactStatic o cualquier cosa que desees. Solo tengo que incrustar mi configuración de MDX en mi Webpack o relab, y todo funcionará libremente.

Pero esto está totalmente desnudo en el sentido de que no tengo ningún preajuste, no tengo ningún diseño, ningún playground, ninguna prop, más sobre eso más adelante. Así que tienes que hacer todo lo que quieras por ti mismo. Eres totalmente libre, esto es completamente flexible, pero es mucho trabajo al principio solo para tener algo funcionando y una documentation funcionando.

Esto es realmente, realmente útil si solo quieres producir un Macdon con sintaxis JSX. Por otro lado, tienes soluciones orientadas a la documentation que incrustan MDX en primer lugar y que proporcionan cualquier tipo de herramienta que necesites para incrustar tu documentation en algún momento con un diseño adecuado, una tabla de props adecuada, playgrounds adecuados, etc. Esta es una solución como Storybook con soporte nativo de páginas MDX o Dubbd. Viene con más restricciones porque es un marco de documentation, pero esto es realmente útil si lo que buscas es producir documentation y no solo producir Macdon con componentes en ellos. Si estás buscando una solución de documentation, te animo a que eches un vistazo a herramientas de documentation orientadas como Storybook, Duxy, etc., con soporte nativo de MDX en ellas. Porque te brindan todo lo que necesitas para simplemente producir tu propia documentation con ellas.

Ahora tienes que organizar tu proyecto. Cuando estás trabajando en una documentation que está relacionada con componentes, es sentido común incrustar la documentation en el propio componente, en lugar de tener una documentation que está decorada a partir de los componentes, debes incrustarlo todo en ellos. Esta es la vista de Backlight.

Backlight es una herramienta en la que estamos trabajando en DivRiots. Es un editor de sistemas de diseño. Por lo tanto, está totalmente orientado a componentes. Cada parte de la interfaz de separación de preocupaciones está orientada a componentes. Entonces, cuando tengo mis componentes, puedo escribir mi código en mis componentes, pero más específicamente, puedo tener mis historias, mis pruebas, mi documentation, mis herramientas de diseño, todo está incrustado en mi componente. Así que tengo uno superior, donde tengo un gran readme o una gran descripción general de mi aplicación. Ese es mi componente superior, finalmente. Cada vez que quiero tener una documentation relacionada con un componente dedicado, como mi botón, solo tengo que ir a mi botón, abrir la carpeta de documentación en la carpeta de mi componente, que es la carpeta de mi botón, y en mi carpeta de documentation, tengo todo lo relacionado con mi componente, con mi botón, escrito directamente en MDX con soporte de GSX, en Madinx, y con esta sintaxis de MDX, puedo importar mi botón directamente en mi documentation. Veamos cómo. Entonces, tenemos un componente GSX. Se ejecutan en un entorno aislado, que reacciona al entorno de envoltura de nuestro componente. Así que solo quiero incrustarlo todo de la misma manera. Entonces, cómo trabajar con ellos con tu propio playground. El hecho es que MDX es demasiado básico. Necesitamos algo más avanzado para trabajar con ellos. Hablé de los playgrounds y las tablas de props. Los playgrounds son finalmente una especie de sandbox que puedo usar para renderizar directamente cualquier tipo de componente directamente en mi documentation. Así que con mi playground, puedo escribir mi componente o incrustarlo directamente, y mi playground estará listo para extraer cualquier parte de él para mi proceso de renderizado. Puedo tener una sola importación de mis componentes, y puedo tenerla en la vista de renderizado, la vista de compilación, una vista EST, lo que quiera. Y este playground me permite tener una sola importación en mi MDX, y esto está renderizando cada parte de mis diferentes vistas de mis componentes y lo que quiero. Otra cosa es la tabla de props. Porque mi componente viene con diferentes props que me permiten personalizarlo, quiero tenerlos directamente en mi documentation para ver cómo se supone que funcionan mis componentes. Así que esto es una especie de reflector para las propiedades del componente. Esto se genera automáticamente con cualquier tipo de propiedades que pueda exponer desde mi componente. Así que esto está actualizado porque todo lo que tengo que hacer es poner algo como, dame la tabla de props de este componente y todo funciona. Esta es la vista de