Cómo MDX es un cambio de juego para la Documentación de tu Proyecto React

Rate this content
Bookmark
SlidesGithub

La documentación es esencial para cualquier proyecto y realmente puede "hacerlo o romperlo". Sin embargo, la documentación requiere tiempo para redactar y a veces puede ser olvidada, o las actualizaciones y enmiendas a ella quedan atrás a medida que avanza el proyecto. Además, crear tu documentación con Markdown tiene sus limitaciones, por lo que es posible que no termines con el resultado que deseas o que tu colaborador necesita.


Al usar MDX puedes combinar Markdown con código e integrarlo en tu proyecto React. La documentación se convierte en un proceso más eficiente y fluido y, ¿me atrevo a decirlo... divertido?

Eddie Jaoude
Eddie Jaoude
28 min
08 Dec, 2023

Comments

Sign in or register to post your comment.

Video Summary and Transcription

Una buena documentación es crucial y puede hacer o deshacer un proyecto. El boca a boca es importante en la industria, y una gran documentación puede atraer usuarios. MDX es una herramienta poderosa para escribir documentación, permitiendo la personalización y reutilización de componentes. La documentación debe ser tratada como código, con pruebas y mejora continua. El uso responsable de la IA es importante, y se debe utilizar un enfoque equilibrado para la documentación, incluyendo comentarios en línea y diferentes formatos.

1. Introducción a Docs con MDX

Short description:

¡Hola, React Day Berlin! Hoy, hablaré sobre Docs con MDX y cómo puede ser un cambio de juego para tu proyecto. La buena documentación es crucial, pero no muchas personas quieren escribirla. La documentación incorrecta y desactualizada me frustra. Mejoremos los números al final de mi charla. Los documentos son tan importantes como el código. Recuerda, cada solicitud de extracción con cambios de código también debería tener pruebas y documentos.

Muchas gracias por esa cálida bienvenida. Bueno, hola, React Day Berlin. Mi nombre es Eddie Chow y estoy súper emocionado de geek con ustedes hoy sobre Docs con MDX y cómo puede ser un cambio de juego para tu proyecto.

Todos queremos buena documentación, pero parece que no muchas personas quieren escribirla. Me frustro cuando los documentos no existen. Y también me frustro cuando tienen un ejemplo de hola mundo. Quiero un ejemplo del mundo real. ¿Pero sabes lo que realmente, realmente me molesta? Cuando la documentación es incorrecta y está desactualizada. Y desafortunadamente, sucede con demasiada frecuencia. Y permíteme aclarar, por bueno, solo quiero decir correcto, actualizado, y se ve bien. No creo que sea demasiado pedir.

Quiero decir, ¿a quién le gusta leer buena documentación? Levantemos las manos. Quiero decir, esperemos que la mayoría de nosotros. Genial. Muchas gracias. Genial verlos a todos despiertos también. Como dije, nada sofisticado, es lo que esperamos. Quiero decir, ¿a quién le gusta escribir documentación? Bueno, algunas personas, algunas personas no están seguras. Bueno, esperemos que podamos mejorar esos números al final de mi charla.

Los documentos son tan importantes como el código. Y si hay algo que debes recordar de toda esta charla, por favor recuerda eso. Podríamos no tratarlo de esa manera, sin embargo. No obtenemos la misma emoción. Y tampoco obtenemos el mismo reconocimiento de nuestros pares. Cuando alguien dice, escribí esta característica genial, utilicé la biblioteca X, y todos están como, oh sí, genial. Y si alguien dice, documenté la característica X, literalmente silencio, no obtienes ese mismo reconocimiento. Y creo que eso también tiene un papel que jugar. Pero esperemos que todos podamos estar de acuerdo en que la documentación es importante, y es nuestra responsabilidad tener buena documentación. Las pruebas también son realmente importantes, pero eso es una discusión aparte, y hablamos de eso ayer aquí en TestJS. Así que creo que cada solicitud de extracción que tiene cambios de código también debería tener pruebas y documentos.

2. Importancia de la Documentación

Short description:

¿Por qué es importante la documentación? La documentación desactualizada puede ser peor que no tener documentación. Puede confundir a los usuarios y causar frustración. Al igual que montar en bicicleta sin frenos, la documentación debe ser confiable. Los pasos faltantes en la documentación pueden llevar a errores y confusión. Es importante contribuir a los proyectos de código abierto revisando y mejorando la documentación.

¿Por qué? Porque todo debe ser revisado. ¿Qué es peor que no tener documentation? Sí, hay algo peor que no tener documentation. La documentation desactualizada. ¿Por qué? Porque la gente confía en ella. Entonces, cuando algo sale mal, es aún más doloroso. Estamos guiando a las personas por el camino equivocado, por lo que no tener documentación puede ser mejor. Las personas saben que deben mirar el código, o intentar descifrarlo, o llamar a un amigo.

¿Alguna vez has montado una bicicleta sin frenos? Yo sí lo he hecho. A principios de este año en Bangkok, estábamos en un hotel, queríamos ir al parque, y nos dijeron que podíamos tomar prestadas sus bicicletas. Pero no tenían frenos. Pero como sabíamos que no tenía frenos, fuimos más despacio. Me aseguré de que Sarah fuera delante, para poder usarla para detenerme. No, solo estoy bromeando. Pero si una bicicleta tiene frenos, esperas que funcionen. Y lo mismo ocurre con la documentation.

Quiero decir, ¿cuántos de ustedes han visto esto antes? Estoy seguro de que lo han visto muchas veces. Mi proyecto principal, y luego no hay documentation. Ese es un escenario. Otro escenario es la documentación con pasos faltantes. Espero que algunas personas puedan gritar cuáles son los dos pasos que faltan aquí. Sí, antes de instalar las dependencias, navega al nuevo directorio que fue creado por el clon de Git, luego instala las dependencias y luego ejecuta npm run dev. No hay nada malo con esto. Esto no es incorrecto. Solo faltan algunos pasos. Si alguien obtiene un error en ese segundo paso y lo busca en Google, probablemente obtendrá, ya sabes, intenta instalar las dependencias. Bien, package.js no se encuentra. Correcto, navega al directorio, instala las dependencias. Y llegarán allí porque esto es genial. Y por cierto, verás esto en muchos proyectos de código abierto, por lo que una excelente manera de contribuir es revisar la documentation y no hacer suposiciones porque si estás familiarizado con proyectos como este, entonces sabrás qué comandos ejecutar. Pero las personas que son nuevas en la tecnología o en el proyecto no lo sabrán.

QnA

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

Full Stack Documentation
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.
Gateway to React: The React.dev Story
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.
Opensource Documentation—Tales from React and React Native
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
Documenting components with stories
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 for Library Authors: Harnessing the Power of TypeScript for DX
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. 

The Legendary Fountain of Truth: Componentize Your Documentation!
React Advanced Conference 2021React Advanced Conference 2021
24 min
The Legendary Fountain of Truth: Componentize Your Documentation!
"In Space, No One Can Hear You Scream." The same goes for your super-brand-new-revolutionary project: Documentation is the key to get people speaking about it.Building well-fitted documentation can be tricky. Having it updated each time you release a new feature had to be a challenging part of your adventure. We tried many things to prevent the gap between doc and code: code-generated documentation, live examples a-la-Storybook, REPL...It's time for a new era of documentation where people-oriented content lives along with code examples: this talk will guide you from Documentation Best Practices – covered from years of FOSS collaborative documentation – to the new fancy world of Components in Markdown: MDX, MDJS, MD Vite, and all.Let's build shiny documentation for brilliant people!