Componentize your documentation

Speaker 1: So thanks a lot. Thanks for joining me today, for this this new edition. So, yeah, we're gonna talk about, documentation and more specifically, what I I'd like to call the legendary fountain of truth by the documentation. So the first thing is that documentation for your project, whatever it is, is definitely a success key. You could work on a really bright on project.

Speaker 1: But if you if your documentation is is lucky and if you're missing important part in it, nobody will know how to use your project or to use your your library, your project, your app, your document, whatever you want. So you do have to stay focused and stay really strong on your documentation. But it's not always that easy because when we talk about documenting code, how our code often desync from our documentation because we are writing some example, but we can't remaintain or sustain our documentation in time and keep it in sync with the rest of the code base because no one likes to write documentation. I don't like to write documentation, and you probably don't like that too. So we need to find a way to to embed the rest of our teammates, especially developers, in this process to write advanced documentations that could be staying sync with the rest of of your your code base.

Speaker 1: So we need a single source of truth that we need to edit once and to have it available everywhere in our documentation and in our code base. So the fact is, right now, we are more and more changing the way we are developing and working on new apps and new content, and we entered in the the component driven development era. So why working on component at first? The first reason is that it improved the the development process because it's faster to develop a component at once rather than working on on the rural application. It's simple to maintain.

Speaker 1: It's better for use usability. It help you to write good test and advanced tests. It helps a lot of people to to just understand the way each part of your application is working and how to to improve just a single part, a single button, or a single pieces of of of your interface. And it's better for the rest of your system. So because we have those code bases that are components oriented, we should probably work with them and embed them directly in our documentation to keep it in sync with the rest of the documents.

Speaker 1: So this is where MDX is entering on stage. So right now, your documentation is probably written in or something like that because it's just easier to write rather than working at HTML because it's just a synthetic sugar in it with a few just a few few few elements to to to to to tag your your component. So it's easy to read, easy to contribute to contribute for the rest of your team and your contributors and your teammates. Everybody could write a Python file. It's really easy.

Speaker 1: But the problem is is it's too simple to to write an advanced documentation, especially if you want to have some kind of advanced example right embedded in your documentation. So we are now using we want to use the MDX syntax. So MDX syntax is no more than having GSX rights available in your Macdon files, which means that I have a Macdon. I can add some kind of components in it. I still stick on my on my standard Macdon flavor, but this Macdon file is converted to a GSX AST, and this GSX is then converted to HTML.

Speaker 1: So I could write content like just importing components right in my Magnum file, put it put the these components the same way I I could write HTML directly in my my Magnum, having the the the advantage of using my document and my components directly in my Magnum files. So it's a it's a big improvement if you want to embed some content in the in it. You have different way to embed the components right in your documents. The first one is probably looking for naked stacks, like, I don't know, any static site generator like Gatsby or or React that expire or whatever whatever you need. You could embed the MDX interpreter right in those generators.

Speaker 1: So it's really flexible, but it's not really documentation oriented. So you have to develop everything that you need for your own project to be ready to handbag your own code and your own elements right in your documentation. On the other side, we have some kind of component documentation oriented frameworks, like Storybook with with MDX in in support in their pages or Doxy or something like that. There there is more constraint because they are document documentation frameworks. But you have the the the advantage of using playgrounds and props table and so on in it.

Speaker 1: So it's totally related to you and your project and what you want to use. Do you want flexibility but on naked solution or advanced solutions that are embedding everything for you? The main piece of the main takeaway of this talk is probably you have to to stay focused on the organization of your project. This is a screenshot of Backlight, which is a design system editor we're working on at my company. But the interesting thing with it is that rather than working on a an overall documentation for the whole project, we are specifically focusing on each component.

Speaker 1: So each component hampered its own code along the its own stories, its own test, and its own documentation by itself, which mean that you document each component in a in a way, And you could have top components in them, like an introduction components or use case components that help you to point to the different part of your application. But each part of your your interface, your application, each component is embedding its own documentation by itself. So how to improve the way to write your documentation with MDX right now? The problem is MDX is too low level. It allows you to embed components right in your Magnum file, but that's all.

Speaker 1: So we need an advanced way to use the the this power. And this is where Playground's magic enter stage. With it, you just write once your code. You embed it directly in the playground component, which is a wrapper that allow you to render the the result of your component and the code used and the different variants. Like, you could write a series of stories for your component.

Speaker 1: You could do that directly in a playground. So in your final documentation, we'll embed a whole placeholder whole placeholder, sorry, with audio component in it and the different code that you will use to to to to to put in front and to embed it in your final application. You could also use props tables that are reflecting the content of your component to present the different variants and the different properties available on your component, allowing you to explain for your user and demonstrate how to use each properties or to play with them so you could easily have an example live example directly in your documentation. So finally, we're going to coding our final documentation because we know a format that allow us to import the command the component and the elements that we want to document directly from our record base. We could put some explanation and some text content to to help people to understand and gather the whole way and the whole information on how the component is working.

Speaker 1: And then we could directly put some advanced playgrounds or description on prop table and so on for the dedicated component we are currently documenting. So we could reflect everything from the code and extract the content from the code. Like, we we extract content from GS doc comments directly. So, finally, our code is just a template that we could hydrate with our our code base directly to have a live documentation in it. So migrating from an existing code content and existing code base to MDX is pretty much easy because your documentation is probably already in a markdown format.

Speaker 1: So it's not just it's just taking your existing markdown files and putting some advanced playgrounds and props table and description components in the in it, but that's all. You have to organize your documentation in a component way. So split probably your documentation and gather every part of your documentation along the code directly. You have to make your choice and pick the right tool. Probably, you wanna use a a documentation oriented framework, but you could also use a a naked solution or a doc platform if you want.

Speaker 1: But choose the right tool for you, and then you you could start to play with your your embedded component in your documentation right now. The fun fact is that MDX is just paving the way. This is really nice if you want to use some kind of advanced g s six component, like a React component or something like that. But if you are focusing on something more abstracted, we have another format that is called g s MDGS, and MDGS is doing exactly the same thing, except it's it's doing it by using existing code blocks in Marathon, but specifying the the destination of the code block. So you could add description like, this is a script, and I want to import my component, or this is a previous story, or this is a story, or this is I don't know.

Speaker 1: Whatever you want. There is a lot of of definition. So if you are working on a a GSX application, GSX format, then stay focused on MDX. But if you want something more abstracted and more JavaScript compliant, then MDGS is definitely what you are looking for. Just keep in mind that writing documentation outside of writing the code, it's 39¢.

Speaker 1: You do have to write them in the same way and keep them in sync at all. And stay focused on advanced tools rather than reinventing the wheel each way each time. So thank you very much. That's all for me. I'm Mads.

Speaker 1: I'm principal developer advocate at where we are baking a lot of dev tools dedicated to components. So that's why that's why I'm here for you. Same thing. Thanks for for everything. Thanks for having me again.