Presentando React View

This ad is not shown to multipass and full ticket holders
React Summit US
React Summit US 2025
November 18 - 21, 2025
New York, US & Online
The biggest React conference in the US
Learn More
In partnership with Focus Reactive
Upcoming event
React Summit US 2025
React Summit US 2025
November 18 - 21, 2025. New York, US & Online
Learn more
Bookmark
Rate this content

¡Así que has construido una biblioteca de componentes! ¡Felicidades! Estoy seguro de que es increíble, pero ¿has puesto el mismo esfuerzo en su documentación? Las bibliotecas de componentes tienden a tener APIs gigantes, docenas de componentes, cientos de props y miles de combinaciones. Eso es mucha información para desempacar.


Podríamos hacer la documentación muy extensa o... súper interactiva. Combinamos vistas previas de componentes, documentación de API, edición de props y edición de código en una experiencia única y fluida. Puedes explorar rápidamente varias configuraciones de cada componente mientras ves cómo se escribe el código.


Esta charla te mostrará cómo aprovechar herramientas y conceptos comunes como Prettier, babel y transformaciones AST para construir una documentación que literalmente puede trabajar para ti.

This talk has been presented at React Summit 2020, check out the latest edition of this React Conference.

FAQ

BaseWeb es una biblioteca de componentes de React implementada como parte del sistema de diseño de Uber, usada en todas sus aplicaciones para proporcionar una experiencia de usuario coherente y eficiente.

ReactJS es un marco basado en JavaScript que permite escribir aplicaciones interactivas y componentes de UI de manera eficiente. Se puede integrar dentro de un marco existente y se usa ampliamente en el desarrollo web.

La documentación es crucial porque facilita a los desarrolladores entender y utilizar correctamente las herramientas y componentes, lo que ahorra tiempo y reduce la necesidad de soporte continuo.

Wojciech Miksiu sugiere invertir en documentación de calidad para reducir las consultas repetitivas y apoyar mejor a los usuarios. Experimentar con diferentes tipos de documentación y utilizar herramientas como Babel y Prettier son prácticas recomendadas.

React View es un componente de React que permite visualizar y editar componentes de React en tiempo real, generando automáticamente el código fuente necesario. Funciona de manera complementaria a Storybook, permitiendo una integración fácil y enriqueciendo la experiencia de documentación.

Mantener la documentación y el código en el mismo repositorio es esencial para asegurar que cualquier cambio en el código se refleje en la documentación. Esto ayuda a evitar la desactualización y asegura que la documentación sea fiable y útil.

Vojtech Miksu
Vojtech Miksu
30 min
17 Jun, 2021

Comments

Sign in or register to post your comment.
Video Summary and Transcription
ReactJS es un framework basado en JavaScript que enfatiza la importancia de construir una documentación increíble para reducir preguntas. El ponente discute el sitio web personalizado construido usando Next.js y MDX, y los desafíos de lidiar con JSX y el proceso de compilación. La charla también aborda la interacción con NAPs, la extracción de información del código utilizando AST y los beneficios de usar Babel y AST Explorer. Se explica el proceso de construcción y generación de código con AST, junto con la importancia de la documentación y ReactVue. El ponente también proporciona información sobre cómo comenzar con la documentación, construir documentación personalizada y mantenerla sincronizada con el código.
Available in English: Introducing React View

1. Introducción a ReactJS y Documentación

Short description:

ReactJS es un lenguaje de JavaScript que utiliza tanto Python como Python. Es un lenguaje basado en JavaScript que se puede utilizar para escribir JavaScript para cualquier lenguaje. Es un marco que te permite usar ReactJS de muchas formas. Hoy, hablaré sobre la documentación y la importancia de construir una documentación increíble para reducir la cantidad de preguntas en nuestros chats y problemas de GitHub.

¿Cómo funciona ReactJS? ReactJS es un lenguaje de JavaScript que utiliza tanto Python como Python. Es un lenguaje basado en JavaScript que se puede utilizar para escribir JavaScript para cualquier lenguaje. Es un marco que te permite escribir JavaScript en un marco existente. ReactJS te permite usar ReactJS de muchas formas.

¿Cómo funciona ReactJS? Hola, mi nombre es Wojciech Miksiu y hoy hablaré sobre la documentación. Mi trabajo consiste en construir una biblioteca de componentes de React llamada baseweb y otras herramientas web en Uber. Baseweb es una implementación de nuestro sistema de diseño y lo utilizamos en todas las aplicaciones. Así que hablemos de la documentación. Es algo que la mayoría de nosotros usamos todos los días y es absolutamente esencial. Todos los días estamos sentados en nuestros escritorios tratando de aprender cosas leyendo y solo a veces nos detenemos a escribir unas pocas líneas de código. Y hay muchas fuentes diferentes de documentación. Tenemos libros, MDN, Stack Overflow, comentarios en el código o simplemente buscamos cosas al azar hasta que nos rendimos y preguntamos a nuestros colegas en Slack.

Pero, ¿cuál es mi verdadera motivación para hablar de esto hoy? Me uní a la empresa hace dos años y esta fue la propuesta que me hicieron. Únete a nosotros. Estarás construyendo componentes de React. Eso sonaba increíble y me convencieron de inmediato. Sin embargo, la realidad del trabajo orientado a la plataforma es ligeramente diferente. Se parece más a este gráfico. Y francamente, es algo bueno. Si nadie usa tus cosas, significa que si nadie te hace preguntas, significa que nadie usa tus cosas y sería terrible. Así que se podría decir que mi equipo se convirtió en víctima de su propio éxito. Cuando comenzamos BaseWeb hace dos años, apenas se usaba y teníamos mucho tiempo para simplemente escribir código, pero luego el uso aumentó. Ahora hay más de 600 aplicaciones solo en Uber y eso se traduce en casi mil desarrolladores. Además, nuestra biblioteca tiene una gran superficie de API. Hay más de 60 componentes, cientos de preparativos y prácticamente infinitas posibilidades. También tenemos muchos colaboradores y usuarios externos. Por lo tanto, naturalmente, pasamos mucho tiempo brindando soporte. La pregunta era, ¿podemos recuperar algo de este tiempo? Creo firmemente que si construimos una documentación increíble, podemos reducir significativamente la cantidad de preguntas en nuestros chats y problemas de GitHub. Además, realizamos encuestas frecuentes. Y la documentación siempre es el tema más mencionado.

2. Importance of Documentation and Custom Website

Short description:

Mi equipo invierte tiempo en experimentar con diferentes tipos de documentación. Te mostraré versiones antiguas de nuestro sitio web de documentación y explicaré por qué no era lo suficientemente bueno. Lanzamos nuestro propio sitio web personalizado basado en Next.js y MDX. Algunos tipos estáticos son demasiado complicados y no legibles para los humanos. Agregar más ejemplos puede resultar abrumador. Creamos un espacio de juego para nuestros componentes para mostrarlos y explorarlos.

Entonces, mi equipo ahora invierte mucho tiempo en experimentar con diferentes tipos de documentación. Espero que hasta ahora haya dejado claro por qué la documentación es tan importante. Aquí está la agenda de la charla. Te mostraré algunas versiones antiguas de nuestro sitio web de documentación y explicaré por qué no era lo suficientemente bueno. Luego, lo que construimos con React y usamos hoy. También voy a echar un vistazo bajo el capó y mostrarte algunos conceptos y código relacionados con los compiladores y los árboles de sintaxis abstracta. Y finalmente, la conclusión. Esta es la versión más antigua de nuestra documentación, es simplemente storybook. Es una solución lista para usar que usamos para desarrollar nuestros componentes, pero también para documentarlos. Puedes ver que es simplemente un montón de ejemplos, y en la parte inferior puedes ver el archivo de lectura donde documentamos nuestras propiedades. Pero a medida que crecimos en número de componentes, queríamos tener algo más estructurado y personalizado. Así que lanzamos nuestro propio sitio web personalizado basado en Next.js y MDX. Ahora los componentes están en diferentes categorías, la página en sí está más estructurada. Cada ejemplo tiene su propio código fuente que se escribe manualmente, y en la parte inferior tenemos una documentación de propiedades generada en función de los tipos estáticos. Y esto funciona bastante bien, hasta que deja de hacerlo. Algunos tipos estáticos son demasiado complicados y no son realmente legibles para los humanos. Además, muchas propiedades están destinadas a ser utilizadas solo internamente, cuando se componen con otros componentes. Pero ahora las exponemos en la API pública, y eso solo confunde. Intentamos ajustar esto muchas, muchas veces, pero nunca fue confiable y no fue suficiente como fuente principal de documentación. Los desarrolladores siempre pueden darse cuenta cuando algo está generado automáticamente, y no les encantará precisamente. ¿Por qué deberían hacer un esfuerzo adicional para leerlo, si tú no hiciste ningún esfuerzo para crearlo? Entonces, ¿qué tal agregar muchos ejemplos? ¿A quién no le gustan más ejemplos? Este es nuestro componente técnico. Es bastante simple, y sin embargo, hay 384 permutaciones diferentes de él. ¿Podemos mostrar 384 ejemplos en una sola página? Claro. ¿Será abrumador? Absolutamente. Y lo mismo ocurre con otros componentes. Si hay un número limitado de ejemplos que podemos presentar para no abrumar a nuestros usuarios, ¿qué más podemos hacer? Bueno, vamos a desactivar y explorar estas permutaciones. Permíteme mostrarte lo que construimos.

Entonces, esto es como un espacio de juego que construimos para nuestros componentes. En primer lugar, quieres mostrar el propio componente. La segunda parte más importante es probablemente el propio código fuente.

3. Editing Source Code and JSX Compilation

Short description:

Puedes editar el código fuente en tiempo real y se mostrarán los errores de sintaxis. Al pasar el cursor sobre los componentes, se muestran sus tipos estáticos. Se pueden crear funciones de JavaScript a partir de cadenas utilizando una API útil. Sin embargo, al tratar con JSX, se necesita un compilador para transformarlo en React.createElement. Babel se puede utilizar en el navegador con este propósito. El componente resultante y el código fuente interactivo se pueden formatear, copiar y compartir de manera conveniente.

Lo bueno del código fuente es que puedes editarlo en tiempo real. Y a medida que escribes, el componente cambia. Si cometes un error de sintaxis, simplemente te decimos qué está mal. También agregamos esta función donde puedes pasar el cursor sobre diferentes componentes y ver sus tipos estáticos. Esta es una característica bastante común en muchas documentaciones.

¿Alguna vez te has preguntado cómo funciona esto en tu navegador? Hay una API útil para crear funciones de JavaScript a partir de cadenas. El primer argumento son los parámetros de la nueva función seguidos del cuerpo. A diferencia de una función val, esto se ejecuta solo con un alcance global. Entonces, todo lo que quieras pasar y usar en esta función, debes pasarlo como argumento.

Ahora podemos ejecutar dinámicamente cualquier JavaScript desde una cadena. Pero, ¿qué pasa si no tratamos solo con JavaScript plano? En realidad, casi nunca lo hacemos. Todos nuestros componentes usan JSX. Probablemente hayas visto qué sucede si intentas ejecutar JSX en tu navegador. Obtienes un error de sintaxis sobre un token inesperado. Realmente no podemos pedirle a las personas que escriban React, createElement en lugar de JSX. Entonces, necesitamos introducir un paso adicional, un proceso adicional. Necesitamos agregar un compilador. ¿Recuerdas a Babel? La mayoría de nosotros lo usamos cuando necesitamos compilar nuestras aplicaciones. Pero también podemos usarlo en nuestro navegador para compilar nuestro JSX en React, createElement. Usamos la función de transformación de Babel core. Cargamos el preset de React. Le pasamos nuestro componente. Y devuelve la llamada a React createElement. Así que esto funciona bastante bien. Ahora tenemos el componente. Tenemos el código fuente interactivo. Permíteme también editar algunas funciones convenientes. Por ejemplo, a los desarrolladores les gusta formatear su código para que sea más legible antes de copiarlo y pegarlo. Puedes copiar el código en el portapapeles. Puedes obtener un enlace permanente.

4. Interacting with NAPs and Extracting Information

Short description:

Puedes interactuar con los NAPs, que representan cada prop del componente. El estado se sincroniza en todas las partes, lo que te permite copiar y pegar el componente exacto en su estado actual. Además, aún puedes cambiar el código fuente y ver las actualizaciones reflejadas en el estado. Para describir las propiedades del botón, se utiliza un formato de configuración simple. La extracción de información del código se realiza convirtiéndolo en un árbol de sintaxis abstracta, lo que proporciona un enfoque más poderoso.

Puedes volver al estado inicial. Y también puedes iniciar CodeSandbox y hacer ediciones más serias, si lo deseas. Esto es genial, pero a veces ni siquiera sabes qué otras props puedes usar para este componente. Entonces, necesitas algún tipo de API de props o documentación de props.

Agregamos esta parte adicional que llamamos NAPs. Cada prop está representada por un solo NAP, y también puedes interactuar con él. A medida que cambio este valor, puedes ver que se actualiza el componente en sí. Pero lo más importante, también se actualiza el código fuente. Este estado se sincroniza en todas estas tres partes. Y aún mejor, por ejemplo, si cambio este tipo a secundario, puedes ver que incluso cambia la importación. Entonces, esto es algo que siempre puedes copiar y pegar en tu aplicación y obtener este componente exacto en este estado exacto.

No solo puedo interactuar con estos NAPs, también puedo seguir cambiando el código fuente en sí. Y puedes ver que, nuevamente, se actualiza el estado aquí, por lo que esta casilla de verificación ahora está marcada y el componente está en estado de carga. ¿Cómo funciona esto? En primer lugar, debemos describir de alguna manera qué propiedades tiene nuestro botón. Podemos renderizar los NAPs. Hemos creado un formato de configuración simple. Aquí tienes un ejemplo. Para cada prop, puedes establecer el nombre, el tipo y la descripción.

Y, cuando actualizamos el código, ahora necesitamos extraer algunas partes de información de él. Necesitamos los nombres y valores de las props para poder mostrarlos en nuestros NAPs. La primera solución rápida sería usar una expresión regular, como aquí. Aquí estamos buscando un elemento JSX y obteniendo las partes con props e hijos. Funciona, pero es extremadamente frágil. ¿Qué pasa si tenemos varios componentes? ¿Qué pasa si están anidados? ¿Cómo diferenciarlos? Ahora el código es solo una cadena larga y tonta. No tenemos una comprensión más profunda de lo que realmente representa. Entonces no podemos hacer mucho al respecto. Necesitamos un enfoque completamente diferente y más poderoso. Necesitamos convertir nuestro código en un árbol. El árbol de sintaxis abstracta. Afortunadamente, ya tenemos una herramienta para eso en nuestro proyecto.

5. Understanding Babel and AST Explorer

Short description:

Babel crea un AST a partir del código que le pasas. AST Explorer es una herramienta útil para inspeccionar ASTs. Ayuda a identificar las diferentes partes del código y sus nodos correspondientes, como identificadores JSX y literales de cadena.

Es Babel. Para que Babel haga algo con tu código, también necesita esta comprensión más profunda de su significado. Así que siempre comienza creando un AST a partir del código que le pasas. Puedes inspeccionar los AST en esta herramienta muy útil llamada AST Explorer. Aquí está nuestro botón. Estamos usando Babel Parser. Y en el lado derecho, puedes ver las tres representaciones de nuestro código. Ahora, si paso el cursor sobre diferentes partes de nuestro código, puedes ver qué nodo se está resaltando. Por ejemplo, este botón ahora corresponde a este identificador JSX. Si paso sobre el tipo, puedes ver que es solo un atributo JSX y el primario es un literal de cadena. Ahora sé exactamente qué parte de este código es cada una y puedo asegurarme de obtener los valores que necesito obtener.

6. Building and Generating Code with AST

Short description:

Aquí está la implementación: analiza tu código con el analizador de Babel para generar la estructura del árbol. Utiliza la función traverse para encontrar los atributos o props de gsx y guardar sus nombres y valores. También podemos revertir este proceso cambiando los props y actualizando el código. Sin embargo, unir cadenas puede llevar a complicaciones y errores de sintaxis. Construir un árbol de sintaxis abstracta (AST) desde cero proporciona un enfoque más confiable. Una vez que tenemos el AST, podemos utilizar el generador de Babel para convertirlo en código. Para que el código sea más legible, podemos utilizar Prettier, una herramienta popular que utiliza la misma representación AST que Babel.

Entonces aquí está la implementación. Primero, utilizas la función parse de Babel parser y le das tu código, y esto genera la estructura del árbol que viste. Luego utilizamos la función traverse para recorrer este árbol y buscar todos los atributos o props de gsx. Una vez que obtenemos este tipo de nodo, simplemente guardamos el nombre y el valor. Esta es una forma muy sencilla de obtener todos los nombres y valores de los props de nuestro componente.

También demostré que podemos hacerlo al revés. Pude cambiar estos snaps y en realidad estaba actualizando este código. Y por cierto, nunca hemos escrito una sola línea de este código en nuestros ejemplos. Todo esto se genera solo en función de la configuración de los props y el estado de este playground. ¿Cómo funciona este proceso al revés? ¿Cómo generamos realmente un código? Como puedes imaginar, hay algún tipo de estado donde tienes la lista de los nombres y sus valores de los props, y sabes cuál es el nombre del componente. Nuevamente, podríamos intentar algo simple y simplemente unir un montón de cadenas juntas, y esto nos dará el fragmento final y funcionará. Pero se complica bastante rápido con todas las excepciones y casos diferentes. Y también es una forma muy fácil de producir un código que no funciona y tiene errores de sintaxis. Ya aprendimos una lección similar con las expresiones regulares. Entonces, nuevamente, necesitamos un enfoque más confiable.

Ya mencioné los árboles anteriormente y resulta que también puedes construirlos desde cero. Este es un ejemplo simplificado de una función que crea un AST de un elemento JSX. Podemos componer nodos juntos para construir nuestro propio árbol desde cero. Dado que todas estas funciones son de tipo estático, si olvidamos pasar algún valor, obtendremos un error. Y ahora podemos estar seguros de que sea cual sea el script final, funcionará. Por supuesto, ahora tenemos el AST, pero todavía necesitamos convertirlo en código. Una vez que tenemos el AST, podemos utilizar la función generate de Babel generator. Esto simplemente convierte el AST en código. Pero hay un problema. Esto solo dará como resultado una sola línea de código, que no es muy legible. Así que vamos a ser más elegantes y podemos utilizar otra herramienta popular llamada Prettier. Y Prettier utiliza la misma representación AST que Babel para el código. Así que podemos usar Prettier para imprimir un fragmento de código mucho más bonito. Hay muchas otras características de este playground que no tengo tiempo de mostrarte.

7. Final Thoughts on Documentation and ReactVue

Short description:

No todos los componentes son tan simples como un botón. Admitimos varios escenarios complejos, como el uso de estados locales, la anidación de múltiples componentes y la creación de prototipos personalizados. React View es una biblioteca de código abierto con su propia documentación interactiva. La documentación es inmensamente importante tanto para los clientes como para los desarrolladores. Los árboles de sintaxis abstracta y herramientas como Babel y Prettier pueden mejorar enormemente la documentación. Echa un vistazo a ReactVue, un proyecto de código abierto que impulsa nuestros ejemplos y documentación. Tener una especificación de prop para cada componente también se puede traducir en fragmentos de código de VS Code, lo que facilita a los desarrolladores producir nuevo código.

Por ejemplo, no todos los componentes son tan simples como un botón. A veces necesitas incluir... A veces necesitas usar estados locales para hacer que tus ejemplos sean realistas. Nosotros lo admitimos. A veces necesitas anidar múltiples componentes. Nosotros lo admitimos. Incluso puedes querer construir un prototipo personalizado y un NAP personalizado. Nosotros también lo admitimos. Todo esto está preparado en esta biblioteca llamada React View. Es de código abierto. Y tiene su propia documentación interactiva. Así que, por favor, échale un vistazo.

Y aquí van algunas reflexiones finales. En primer lugar, la documentación es inmensamente importante y una parte crítica de cualquier cosa que envíes. Ayuda a tus clientes a usar tu producto. Pero también hazlo por tus propias razones egoístas. Puedes ahorrarte mucho tiempo al no responder preguntas que pueden ser respondidas por una documentación de calidad.

En segundo lugar, ¿cómo podemos mejorar mucho la documentación? Obtén tus superpoderes con los árboles de sintaxis abstracta y herramientas como Babel y Prettier. Ya los usamos para construir nuestras aplicaciones, pero también podemos usarlos para escribir algunas partes aburridas de nuestro código y construir una documentación mucho mejor.

Y finalmente, para comenzar, echa un vistazo a ReactVue. Es de código abierto y alimenta todos los ejemplos de mi charla y nuestra documentación. Y hay una cosa más, encontramos otro uso para tener una especificación de prop para cada componente. Lo tradujimos en fragmentos de código de VS Code. Es una excelente función para usuarios avanzados. Muchas veces, tus desarrolladores ni siquiera necesitan leer la documentación para producir nuevo código. ¿Y qué hay mejor que eso? Si quieres mantenerte actualizado, aquí está mi Twitter. Y gracias por ver. Charlas fantásticas hoy, y la tuya definitivamente se suma a la larga lista de grandes charlas que hemos visto. Y de nuevo, solo... la cita. Ah, tan buena.

8. Getting Started with Documentation and ReactView

Short description:

La documentación es importante. Comienza incrementalmente con Storybook para desarrollar componentes y utiliza sus complementos para la documentación. Si necesitas más, prueba una solución personalizada como Gatsby y MDX. ReactView se puede utilizar junto con Storybook como complemento. Genera código fuente y admite cualquier componente de React. El proceso para nuestra empresa implicó construir la biblioteca de componentes utilizando Storybooks.

Esto es como, sí, la documentación es importante, gente. Una pregunta que me estaba haciendo cuando vi esto, y recordé cómo empecé con la documentación en el pasado. ¿Cómo dirías... cuál es una buena manera para que las personas comiencen a crear documentación? ¿Cuál es el buen punto de partida? Sí, para nosotros también fue un proceso, ¿verdad? Nos llevó un tiempo construir todo el sistema, así que diría que comiences incrementalmente. Creo que Storybook es una gran opción, porque puedes usarlo para desarrollar tus componentes, y tiene algunos complementos realmente geniales, así que también puedes documentarlos. Después de un tiempo, cuando eso no es suficiente, o sientes que necesitas algo más, tal vez deberías usar una solución personalizada. Tuvimos una charla realmente buena sobre Gatsby y MDX. Realmente, realmente me gusta MDX. También lo usamos. Usamos Next.js, es similar. Pero sí, simplemente comienza incrementalmente. Storybook es una excelente manera de comenzar rápidamente. MDX es increíble después.

De hecho, eso me lleva a una pregunta de Forzu del canal, que es, si tengo una biblioteca de muestra de Storybook, ¿debería probar ReactView para la documentación? Nuestro sistema de diseño está bastante integrado con NX y Storybook. ¿Es un complemento o una alternativa a Storybook usar ReactView? También puedes usarlo con Storybook. ReactView es solo un componente de React, por lo que se puede usar en Storybook. En cierto modo, es similar. En Storybook, también tienes estos mapas donde puedes cambiar valores y ver diferentes variantes de tus componentes. ReactView va un paso más allá. Genera el código fuente por ti. Entonces, sí, puedes usarlo al mismo tiempo. Storybook admite cualquier cosa. Simplemente puedes poner cualquier componente de React allí. ReactView es solo otro componente de React, por lo que definitivamente puedes usarlo juntos. Eso es agradable. Eso es bastante genial.

Y mencionaste, volviendo a la pregunta original sobre cómo comenzar, mencionaste que fue un proceso para tu empresa. Entonces, ¿qué dirías que fue el proceso? ¿Cuáles fueron los pasos que tuvieron que seguir? Además de elegir tu tecnología y una solución para producir la documentación, ¿cómo se veía más o menos todo el proceso? Correcto. Primero comenzamos construyendo toda la biblioteca de componentes. Esa era la prioridad, simplemente sacar todos los componentes. Por eso usamos Storybooks.

9. Building Custom Documentation and Search

Short description:

No dedicamos mucho tiempo a construir documentación personalizada. Escuchamos las dificultades de los usuarios e intentamos responder a sus preguntas. Para mejorar la documentación, solicita comentarios a los usuarios y realiza encuestas. La construcción de una documentación personalizada permite abordar preguntas auxiliares y frecuentes. Una buena función de búsqueda es esencial y soluciones de código abierto como Algolia pueden ayudar. Elasticsearch es otra opción.

No dedicamos mucho tiempo a construir documentación personalizada. Pero también tenemos este canal de soporte y estábamos escuchando a las personas. Tienen muchas dificultades para usar nuestros componentes, y siempre intentábamos responder a estas preguntas. Y luego vemos que las personas hacen las mismas preguntas. Pensamos, ¿cómo podríamos reunir estas preguntas y resolverlas en nuestra documentación para que las personas dejen de preguntarnos lo mismo una y otra vez.

Entonces, intenta preguntar a las personas que usan tu documentación, tu proyecto, qué opinan sobre tu documentación, qué falta. Definitivamente te lo dirán porque pasan mucho tiempo buscando respuestas. Así que es como este feedback constante de tus usuarios que realmente mejora tu documentación. Deberías preguntarles con frecuencia, tal vez hacer una encuesta. Eso es realmente genial. También me preguntaba sobre esto. Entonces construiste una biblioteca de componentes y estoy bastante seguro de que tienes muchos componentes, ¿verdad? Y no solo eso. Quiero decir, los componentes son una cosa sobre la que las personas pueden tener preguntas. Pero puede haber preguntas auxiliares o preguntas frecuentes que te hacen que no están necesariamente directamente relacionadas con un componente, sino como la interacción de componentes o algo así. ¿Cómo puedes asegurarte de que los usuarios encuentren las respuestas a sus preguntas dentro de tu extensa documentación?

Sí, esa es una gran pregunta. Esa también fue una de las razones por las que decidimos construir una documentación personalizada, no solo usando storybook. Porque no es suficiente solo documentar componentes, sino que también quieres tener la historia de todo el sistema. Pero que también cubra otras preguntas importantes. Entonces, otra cosa para facilitar esto es tener una buena búsqueda en tu documentación. Tener una buena búsqueda de texto completo es realmente útil. Y hay algunas soluciones gratuitas de código abierto como Algolia, que son realmente buenas y que construyen el índice por ti. Genial. Sí. Eso es bastante genial. Creo que también hay, cómo se llama, Solar y, ah, hay otro que no puedo recordar, Elasticsearch. No, eso es algo diferente. Elasticsearch es una búsqueda de texto completo, sí. Sí, eso también funcionaría. En realidad, no he probado mucho Algolia. También, disculpa.

10. Starting Documentation and Keeping it in Sync

Short description:

Cuándo comenzar a escribir documentación depende del proyecto. Para nuevos prototipos, es mejor evitar la documentación ya que las APIs pueden cambiar con frecuencia. Sin embargo, para proyectos a largo plazo, es más fácil comenzar a documentar desde el principio. Evita depender demasiado de la generación automática y concéntrate en crear documentación legible para los humanos. Mantén la documentación y el código en el mismo lugar para asegurarte de que estén sincronizados.

También, otra cosa que he visto con empresas que finalmente invirtieron en documentación, algunas de ellas lo hicieron demasiado tarde. Si tienes una gran cantidad de contenido para cubrir, crear documentación muy tarde en el proceso es realmente difícil de hacer bien. ¿Dirías que se debe escribir documentación desde el principio, desde el comienzo de un proyecto, o depende de cuándo comenzar a escribir documentación?

Esa es también una buena pregunta. Entonces, si estás construyendo algo completamente nuevo y solo estás haciendo prototipos, puede que no sea lo mejor comenzar con la documentación. Porque probablemente cambiarás las APIs mucho y estarás perdiendo mucho tiempo. Por otro lado, si sabes que lo que estás construyendo es a largo plazo, podría ser mucho más fácil hacerlo al mismo tiempo, como comenzar a documentar todo al mismo tiempo. Porque, ya sabes, cuando quieres lanzar un proyecto, no tienes documentación. Es realmente molesto. Como ahora, tengo que dejar de hacer cualquier cosa y durante las próximas dos semanas, solo voy a escribir un gran bloque de texto. Así que probablemente sea más fácil hacerlo al mismo tiempo, a menos que estés haciendo prototipos de algo nuevo y no estés seguro todavía. Es una especie de compromiso.

Eso es un buen punto. Sí, tiene sentido. Siguiendo esa pregunta, Fauzul pregunta si tenemos recomendaciones como las que hemos visto en la última charla de MDX. Probablemente. Me gustaría mostrar casos de uso como habitaciones de IKEA para mis componentes en la documentación. También, gran charla, dice él. Gracias.

De acuerdo, entonces una recomendación es no depender demasiado de la generación automática. Es muy tentador usar alguna herramienta que extraiga tipos estáticos de tus componentes y simplemente genere toda esta documentación de la API. No estoy diciendo que la documentación de la API no sea útil, pero las personas ya están usando TypeScript, por lo que pueden ver qué APIs pueden usar. Probablemente estén más interesados en casos de uso más profundos, por lo que siempre debes intentar crear tu documentación a medida para escenarios reales. Así que simplemente no confíes en la generación automática. Intenta realmente escribir documentación legible para los humanos, algo que te gustaría ver como desarrollador. Esa sería mi recomendación, y al mismo tiempo, también lo que debes hacer. Dedica tiempo y hazlo agradable, legible para los humanos... incluso divertido, ¿verdad? Queremos divertirnos al leer la documentación.

También, cuando se trata de ser un desarrollador y escribir documentación, otra cosa que noto y también es una mala práctica... Creo que lo único peor que la documentación es la documentación desactualizada. ¿Cómo lidias con el cambio de código y la documentación que no se actualiza? Creo que lo más importante es mantener la documentación y el código en el mismo repositorio, en el mismo lugar. Y simplemente, ya sabes, reutilizar cosas. Si cambio un componente, en realidad va a romper los ejemplos en mi documentación, así que también tengo que arreglar eso. Y también, ya sabes, cualquier función que agregue a cualquier componente, al mismo tiempo también tengo que crear documentación para ello. Entonces, si mantienes estas cosas juntas en el mismo lugar, estando vinculadas, siempre te verás obligado a mantenerlas sincronizadas, lo que realmente ayuda. Esa es una forma genial de abordar esto. Increíble. Wojtek, creo que fue una charla increíble y estoy realmente agradecido de que estuvieras aquí para responder todas tus preguntas, todas las preguntas que hay ahí fuera y también mis preguntas.

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

Una Guía del Comportamiento de Renderizado de React
React Advanced 2022React Advanced 2022
25 min
Una Guía del Comportamiento de Renderizado de React
Top Content
This transcription provides a brief guide to React rendering behavior. It explains the process of rendering, comparing new and old elements, and the importance of pure rendering without side effects. It also covers topics such as batching and double rendering, optimizing rendering and using context and Redux in React. Overall, it offers valuable insights for developers looking to understand and optimize React rendering.
Construyendo Mejores Sitios Web con Remix
React Summit Remote Edition 2021React Summit Remote Edition 2021
33 min
Construyendo Mejores Sitios Web con Remix
Top Content
Remix is a web framework built on React Router that focuses on web fundamentals, accessibility, performance, and flexibility. It delivers real HTML and SEO benefits, and allows for automatic updating of meta tags and styles. It provides features like login functionality, session management, and error handling. Remix is a server-rendered framework that can enhance sites with JavaScript but doesn't require it for basic functionality. It aims to create quality HTML-driven documents and is flexible for use with different web technologies and stacks.
Compilador React Forget - Entendiendo React Idiomático
React Advanced 2023React Advanced 2023
33 min
Compilador React Forget - Entendiendo React Idiomático
Top Content
Joe Savona
Mofei Zhang
2 authors
The Talk discusses React Forget, a compiler built at Meta that aims to optimize client-side React development. It explores the use of memoization to improve performance and the vision of Forget to automatically determine dependencies at build time. Forget is named with an F-word pun and has the potential to optimize server builds and enable dead code elimination. The team plans to make Forget open-source and is focused on ensuring its quality before release.
Uso efectivo de useEffect
React Advanced 2022React Advanced 2022
30 min
Uso efectivo de useEffect
Top Content
Today's Talk explores the use of the useEffect hook in React development, covering topics such as fetching data, handling race conditions and cleanup, and optimizing performance. It also discusses the correct use of useEffect in React 18, the distinction between Activity Effects and Action Effects, and the potential misuse of useEffect. The Talk highlights the benefits of using useQuery or SWR for data fetching, the problems with using useEffect for initializing global singletons, and the use of state machines for handling effects. The speaker also recommends exploring the beta React docs and using tools like the stately.ai editor for visualizing state machines.
Enrutamiento en React 18 y más allá
React Summit 2022React Summit 2022
20 min
Enrutamiento en React 18 y más allá
Top Content
Routing in React 18 brings a native app-like user experience and allows applications to transition between different environments. React Router and Next.js have different approaches to routing, with React Router using component-based routing and Next.js using file system-based routing. React server components provide the primitives to address the disadvantages of multipage applications while maintaining the same user experience. Improving navigation and routing in React involves including loading UI, pre-rendering parts of the screen, and using server components for more performant experiences. Next.js and Remix are moving towards a converging solution by combining component-based routing with file system routing.
Sistemas de Diseño: Caminando la Línea Entre Flexibilidad y Consistencia
React Advanced 2021React Advanced 2021
47 min
Sistemas de Diseño: Caminando la Línea Entre Flexibilidad y Consistencia
Top Content
The Talk discusses the balance between flexibility and consistency in design systems. It explores the API design of the ActionList component and the customization options it offers. The use of component-based APIs and composability is emphasized for flexibility and customization. The Talk also touches on the ActionMenu component and the concept of building for people. The Q&A session covers topics such as component inclusion in design systems, API complexity, and the decision between creating a custom design system or using a component library.

Workshops on related topic

Masterclass de Depuración de Rendimiento de React
React Summit 2023React Summit 2023
170 min
Masterclass de Depuración de Rendimiento de React
Top Content
Featured Workshop
Ivan Akulov
Ivan Akulov
Los primeros intentos de Ivan en la depuración de rendimiento fueron caóticos. Vería una interacción lenta, intentaría una optimización aleatoria, vería que no ayudaba, y seguiría intentando otras optimizaciones hasta que encontraba la correcta (o se rendía).
En aquel entonces, Ivan no sabía cómo usar bien las herramientas de rendimiento. Haría una grabación en Chrome DevTools o React Profiler, la examinaría, intentaría hacer clic en cosas aleatorias, y luego la cerraría frustrado unos minutos después. Ahora, Ivan sabe exactamente dónde y qué buscar. Y en esta masterclass, Ivan te enseñará eso también.
Así es como va a funcionar. Tomaremos una aplicación lenta → la depuraremos (usando herramientas como Chrome DevTools, React Profiler, y why-did-you-render) → identificaremos el cuello de botella → y luego repetiremos, varias veces más. No hablaremos de las soluciones (en el 90% de los casos, es simplemente el viejo y regular useMemo() o memo()). Pero hablaremos de todo lo que viene antes - y aprenderemos a analizar cualquier problema de rendimiento de React, paso a paso.
(Nota: Esta masterclass es más adecuada para ingenieros que ya están familiarizados con cómo funcionan useMemo() y memo() - pero quieren mejorar en el uso de las herramientas de rendimiento alrededor de React. Además, estaremos cubriendo el rendimiento de la interacción, no la velocidad de carga, por lo que no escucharás una palabra sobre Lighthouse 🤐)
Next.js para Desarrolladores de React.js
React Day Berlin 2023React Day Berlin 2023
157 min
Next.js para Desarrolladores de React.js
Top Content
Featured WorkshopFree
Adrian Hajdin
Adrian Hajdin
En esta avanzada masterclass de Next.js, profundizaremos en conceptos clave y técnicas que permiten a los desarrolladores de React.js aprovechar al máximo Next.js. Exploraremos temas avanzados y prácticas prácticas, equipándote con las habilidades necesarias para construir aplicaciones web de alto rendimiento y tomar decisiones arquitectónicas informadas.
Al final de esta masterclass, serás capaz de:1. Comprender los beneficios de los Componentes del Servidor React y su papel en la construcción de aplicaciones React interactivas, renderizadas por el servidor.2. Diferenciar entre el tiempo de ejecución de Edge y Node.js en Next.js y saber cuándo usar cada uno en función de los requisitos de tu proyecto.3. Explorar técnicas avanzadas de Renderizado del Lado del Servidor (SSR), incluyendo streaming, fetching paralelo vs. secuencial, y sincronización de datos.4. Implementar estrategias de caché para mejorar el rendimiento y reducir la carga del servidor en las aplicaciones Next.js.5. Utilizar Acciones React para manejar la mutación compleja del servidor.6. Optimizar tus aplicaciones Next.js para SEO, compartir en redes sociales, y rendimiento general para mejorar la descubrabilidad y la participación del usuario.
Aventuras de Renderizado Concurrente en React 18
React Advanced 2021React Advanced 2021
132 min
Aventuras de Renderizado Concurrente en React 18
Top Content
Featured Workshop
Maurice de Beijer
Maurice de Beijer
Con el lanzamiento de React 18 finalmente obtenemos el tan esperado renderizado concurrente. Pero, ¿cómo va a afectar eso a tu aplicación? ¿Cuáles son los beneficios del renderizado concurrente en React? ¿Qué necesitas hacer para cambiar al renderizado concurrente cuando actualices a React 18? ¿Y qué pasa si no quieres o no puedes usar el renderizado concurrente todavía?

¡Hay algunos cambios de comportamiento de los que debes estar al tanto! En esta masterclass cubriremos todos esos temas y más.

Acompáñame con tu portátil en esta masterclass interactiva. Verás lo fácil que es cambiar al renderizado concurrente en tu aplicación React. Aprenderás todo sobre el renderizado concurrente, SuspenseList, la API startTransition y más.
Consejos sobre React Hooks que solo los profesionales conocen
React Summit Remote Edition 2021React Summit Remote Edition 2021
177 min
Consejos sobre React Hooks que solo los profesionales conocen
Top Content
Featured Workshop
Maurice de Beijer
Maurice de Beijer
La adición de la API de hooks a React fue un cambio bastante importante. Antes de los hooks, la mayoría de los componentos tenían que ser basados en clases. Ahora, con los hooks, estos son a menudo componentes funcionales mucho más simples. Los hooks pueden ser realmente simples de usar. Casi engañosamente simples. Porque todavía hay muchas formas en las que puedes equivocarte con los hooks. Y a menudo resulta que hay muchas formas en las que puedes mejorar tus componentes con una mejor comprensión de cómo se puede usar cada hook de React.Aprenderás todo sobre los pros y los contras de los diversos hooks. Aprenderás cuándo usar useState() versus useReducer(). Veremos cómo usar useContext() de manera eficiente. Verás cuándo usar useLayoutEffect() y cuándo useEffect() es mejor.
Presentando FlashList: Construyamos juntos una lista performante en React Native
React Advanced 2022React Advanced 2022
81 min
Presentando FlashList: Construyamos juntos una lista performante en React Native
Top Content
Featured Workshop
David Cortés Fulla
Marek Fořt
Talha Naqvi
3 authors
En esta masterclass aprenderás por qué creamos FlashList en Shopify y cómo puedes usarlo en tu código hoy. Te mostraremos cómo tomar una lista que no es performante en FlatList y hacerla performante usando FlashList con mínimo esfuerzo. Usaremos herramientas como Flipper, nuestro propio código de benchmarking, y te enseñaremos cómo la API de FlashList puede cubrir casos de uso más complejos y aún así mantener un rendimiento de primera categoría.Sabrás:- Breve presentación sobre qué es FlashList, por qué lo construimos, etc.- Migrando de FlatList a FlashList- Enseñando cómo escribir una lista performante- Utilizando las herramientas proporcionadas por la biblioteca FlashList (principalmente el hook useBenchmark)- Usando los plugins de Flipper (gráfico de llamas, nuestro perfilador de listas, perfilador de UI & JS FPS, etc.)- Optimizando el rendimiento de FlashList utilizando props más avanzados como `getType`- 5-6 tareas de muestra donde descubriremos y solucionaremos problemas juntos- Preguntas y respuestas con el equipo de Shopify
React, TypeScript y TDD
React Advanced 2021React Advanced 2021
174 min
React, TypeScript y TDD
Top Content
Featured Workshop
Paul Everitt
Paul Everitt
ReactJS es extremadamente popular y, por lo tanto, ampliamente soportado. TypeScript está ganando popularidad y, por lo tanto, cada vez más soportado.

¿Los dos juntos? No tanto. Dado que ambos cambian rápidamente, es difícil encontrar materiales de aprendizaje precisos.

¿React+TypeScript, con los IDEs de JetBrains? Esa combinación de tres partes es el tema de esta serie. Mostraremos un poco sobre mucho. Es decir, los pasos clave para ser productivo, en el IDE, para proyectos de React utilizando TypeScript. En el camino, mostraremos el desarrollo guiado por pruebas y enfatizaremos consejos y trucos en el IDE.