The Legendary Fountain of Truth: Componentize Your Documentation!

Hi everyone, nice to have you here. Welcome to this session about documentation in a component-driven development era. So we're going to talk about documentation as a key success of your project. I mean, nevertheless you are working on a library, a single component, a whole design system or a final interface of an application. Your documentation is the key to the success of your project because without a proper documentation, no one is going to have a single clue about how is it working and how you are supposed to use your project or use any parts of your project. So you have to keep your documentation properly associated with your code. Fact is, leaving documentation is a pain today just because if you have to duplicate your code from your code base to your documentation, you obviously lead to a desynchronization at some point of your documentation versus your code base. So you have to keep them in sync. If you want to be ready to just simply use and sustain your documentation in time, so to have your project ready to be used by anyone in the past and in the future. So we tried many things to keep things organized between your documentation and your code base. We tried things like storybook, we tried things like Embed, ERPL in your documentation by itself. We tried many things, but the real truth is that we need a single source of truth. And this single source is your code base by itself, not your documentation, not your examples that will be outdated at some point. You need something that is definitely the single point where everything leaves and this is directly in your code base. So we do have to do something to keep the documentation in sync with the code base. And we do need something to embed your code base in your documentation. So just a reminder about the DATX's framework. This is a documentation framework that many companies are using right now. This documentation framework is oriented in four parts. All these four parts are the dedicated parts to your documentation. And all you have to do is split different elements of your documentation in the same area. So first entry is the readme's. Readme's are the entry point of your documentation. When a user is coming to your new documentation and doesn't have any clue where to start, the readme's are the correct entry point. There are something like getting started guys, this kind of stuff. Something where you can replay all the time the same path and the same steps in your development process and you will have the same result at your hand. This is the really good way to just put your hands in your project. The second part is the O2's. The O2's are more guides or recipes and they are dedicated at how you want to work with this part of the project. How can I embed my project in a react app? How can I use my library with this kind of backend and so on? So the guides presume that you have a preset and in this particular preset, there are guides, there are different recipes on how you could use your project in different aspects of the development. The third part is the FAQ's. You have all the discussions, all the histories. Why is this project of this choice, this particular use of this tool or this preset and so on. This is where all the history of the project is living and it helps to understand why did we choose this particular setup at some point. And it helps to understand how everything interacts together. Then the final parts are main pages in the Unix era or more specifically advanced documentation about a dedicated part. How this component is working, how this library is using at some point in the project. And this is a comprehensive guide of particular deep technical content. So these four parts are attached to four different areas. Readmes and O2s are the practices points. Each time you are asking, okay, I'm working on a new part of documentation and I want to add some new content in it. Which topic is it related on? If it's related to practices, then this is the right point to have a look at. So is it something like an entry point, like a getting started stuff or is it a guide dedicated to more different access in the specific area of specific parts of the development process? So readmes and O2s, this is practice. Where the facts and the main pages are more dedicated to understanding the project and the base of the project. But the readmes and the FAQs are also the learning parts where you are learning how it is working and why it is working this way. Where the O2s are more dedicated to and the main pages are more dedicated to where I want to use the project. Which part do I have to keep an eye on? Is it on the O2s? Is it on the main pages? I am looking for a deep dive technical content or I'm looking to a dedicated guide on this particular topic because this is what I am looking for at this point. So when you have this framework in mind, you are working on a well-fitted documentation for any kind of project. So I do recommend you to keep an eye on the Ataxis framework if you don't know it right now and to try to stack your documentation to it because this is something really, really useful in your everyday work. But we are now working in a component-driven development area. So in this environment, I'm working on components more than any other parts. And this component-driven development brings us a new way to develop and to sync our application because it involves faster development, a simpler maintenance, better reusability, better CDD because every part of your application is separated in small parts, in small components. And when you split your whole front-end interface in components only, then you are able to work on all parts that are isolated in your application. And you are able to just extract your content and to have it running isolated in a sandbox environment. And in this sandbox, your component could be easily maintained, tested, and documented. And this is the part that we are looking for right now. So in this Diataxis framework, with a component-driven development era, how could we mix them all to get the most of the two worlds? What is really interesting is that when you are working like that, this is really easy to extract your component from your application and to put it in a dedicated sandbox, working in it, making some tests, making some live use of this new component, and having it available to be embedded in different parts, different era of your documentation. So your documentation can now be fully exhaustive on why is it working like that, how is this component really useful, how could we really rely on this component in this particular context and so on. So in my Diataxis framework, putting some stuff dedicated to my component in the guides of the READMEs and the O2s and so on is really, really useful because it's easy now to understand, where I could put my documentation for this particular part of my application that is this component, my dropdown, my gallery view, my hero, my button. This is exactly how I want to perform my documentation because when I am looking for a new documentation on a project, what I am looking for is, okay, what are the different components available in my library, how could I use them, how could I make them all, how could I plug them all to just interact between my components, how could I use them in react, in vue, in vue Is Veld, in whatever you want. So this is exactly how we have to twist our mind to just put the documentation related to a component in the right parts of our overall documentation at all. So with that, we are now able to play with the docs live because we could embed our components that is properly isolated from our final application in our documentation at hand. So it's really easy now to just play in our component in a sandbox with this component in our documentation, play with it and just try it, test it, have some kind of experiment, like it at some point. But this is not, it is no matter just because you could use your component in a dedicated area that is a living documentation. So we need to mix this component in our documentation, import it in our documentation and having it lively in here. So how could we do that right now? This is the answer brought by the MDX environment. So MDX is Markdown, but a glorified Markdown. So writing your docs. Right now you are probably using Markdown to write your documentation. This is just syntactic sugar on html. You probably know Markdown because it's almost everywhere right now from GitHub to any CMS or documentation platform or document production platforms. So it's a really simple syntax, easy to read, easy to contribute, even if you're not technical at all, because this is just writing text with some kind of markups that is just simple characters. So it's not that complex. It's compatible with any text editor. It's really simple to use, but it's too simple to use with really complex document. I mean, with Markdown, I can't handle my component in it. So I have to do some stuff. Okay, I can embed html right in my Markdown, but it's not enough. I need something more advanced and I need something more useful when I want to work with it. So this is why we have now the MDX syntax, and the MDX is just JSX embedded in Markdown. Or more than that, this is Markdown converted to JSX that is now converted to html. So this is a step more between the Markdown and the html in the rendering process. This is not just linear from Markdown to html, but this is from Markdown to JSX to html. And in this environment, when I'm working on my Markdown, in fact, I'm working in a JS or more a JSX document so I can import, export any kind of document in it. I could write Markdown in it, but I could also put my document, my component in my document right now in the end. And this is now embedded in my Markdown. And this is rendered in my Markdown at the final process. So this is really useful because now we have components in Markdown directly. So under the hood, this is just the standard Markdown level with the JSX native syntax all mixed together. We could embed external components. We could embed function rendering and external function rendering. We could pass props. We could have typescript native support. We could have anything that we are used to with JSX, but directly in our Markdown. Because in the final steps, this is just a rendering process where I have a Markdown syntax, an MDX syntax. Then this is converted to an AST. This is a JSX AST. Then this JSX AST is converted to an html AST. Then this html AST is converted to html. So this is just a process of different conversion. And this is exactly what we are looking for. We now have syntax, Markdown syntax that is flexible enough to be used to embed any kind of component. So I got a simple MDX layout. I could embed any props in it, any components in it, and I could render anything that I want. That is a regular JSX syntax or a regular Markdown syntax and mix them all. So we now have different environments that are ready to embed the MDX. MDX is really simple. This is just adding a single line of configuration in your webpack config or your webapp config. So this is really easy to do. This is not a complex setup to have. But we now split this environment into two worlds. We have in one side the naked tools that are ready to embed the MDX. I could do MDX with any kind of static generator, from gatsby to react Static to whatever you want. I just have to embed my MDX configuration in my webpack or webapp, and everything will work freely. But this is totally naked in the sense of I don't have any preset. I don't have any layout, any playgrounds, any props, more on that later. So you do have to do anything that you want by yourself. You are totally free. This is completely flexible. But this is a lot of work at first just to have something working and documentation working. But this is really, really handy if you just want to produce a Magdon with JSX syntax. On the other hand, you have documentation-oriented solutions that are embedding MDX at first and that are providing any kind of tools that you need to embed your documentation at some point with proper layouts, proper props table, proper playgrounds, and so on. This is a solution like storybook with native support of MDX pages or WD. It comes with more constraints because this is a documentation framework. But this is really useful. What you are looking for is producing documentation and just not producing Magdon with components in them. So if you are looking for a documentation solution, I do encourage you to have a look on documentation tools oriented like storybook, Dougsy, and so on with MDX native support in them because they are producing every way they give you anything you need to just produce your proper documentation with them. Now you have to organize your project. When you are working on a documentation that is related to components, this is common sense that embedding the documentation in the component itself rather than having a documentation that is decorated from the components. So you have to embed everything in there. This is the Backlight view. Backlight is a tool that we are working to at DeepRiot. This is a design system editor. So it's totally components-oriented. And each part of the interface of separation of concerns oriented to components. So when I have my components, I could write my code in my components. But more specifically, I could have my stories, my tests, my documentation, my design tools, everything is embedded in my component. So I have top one where I have a big readme or a big overview of my application. That is my top components, finally. And each time I want to have a documentation related to a dedicated component like my button, I just have to go in my button, open the doc folder in my component folder, that is my button folder, and in my documentation folder, I have everything related to my component, to my button, written directly in my DOM with JSC support in MaddX. And with this MDX syntax, I could import my button directly in my documentation. Let's see how. So we have JSX components. They run in isolated environment that reacting on the wrapping environment of our components. So I just want to embed everything in the same way. So how to work with them with your home playground? Fact is, MDX is too low-level. You need something more advanced to work with them. I talked about playgrounds and table props. So playgrounds are finally some kind of sandboxes I could use to directly render any kind of components directly in my documentation. So with my playground, I could write my component or embed it directly, and my playground will be ready to extract any part of it to my rendering process. I could have a single view, a single import of my components, and I could have it in the rendering view, the compile view, an EST view, whatever I want. And this playground allows me to just have one import in my MDX, and this is rendering every part of my different views of my components and what I want. Another thing is the props table. Because my component is coming with different props that allow me to customize it, I want to have them directly in my documentation to see how my component is supposed to work. So this is a kind of reflector for component properties. This is auto-build with any kind of properties that I could expose from my component. So this is up to date because all I had to do is just to put something like, give me the props table of this component, and everything is working. This is the view of the storybook props table system. This is just a single line. You just embed a single component that is a reflector of my component. And in my documentation, I have access to any part of the properties of my component at all. So this is really handy if I want to have it. Then you could code from your docs. You could import your component that you want to document. You could write your Mac down as you are used to when you are working in documentation. Then you could embed any kind of elements related to this component. Description, the playground, the props table, everything will be in the single line, aligned with my code because the documentation is not decorated for my components right now. It embeds my component in it. So finally, MDX plus component stories format plus playgrounds plus props table. Boom! This is the best world. You could just have a documentation that is totally related to your components at all. So how to migrate to MDX? You're probably already working on the documentation in the Mac form. So you don't have to add up anything. You just have to organize your documentation from the ADDX framework to your different components. So have it properly isolated, each documentation to each component at the side. Then you could pick your right tool or a naked or a documentation framework tool or a documentation platform. Then you could start to play with your components. And that's all because MDX is just paving the way. This is just the first tool of a new era. And I'm pretty sure that we will have a lot of other formats and a lot of other tools to embed our documentation and improve our components or Yanti documentation. But writing documentation outside of writing is just nonsense. We do have to embed our code in our documentation. And this is the premise of the MDX format. This is what we are looking for. You do have now to focus on advanced and integrated dev tools rather than just reinventing the wheel at some point. You just have to be focused on what you are looking for. This is exactly what we are doing with the tools we are working at DevRiot, like Backlight, of webcomponents.dev. If you have any questions, we will meet in a Q&A session just right now. For everything else, thank you very much. I'm Mads, I'm a principal developer advocate at DevRiot, where we're working on document and components-oriented solutions like webcomponents.dev or Backlight.dev. So that's our design systems-oriented IDE in your browser, directly in your browser, with anything you need in it, like documentation process with MDX, playgrounds, props, table, and so on. Have a look at them. Thank you very much.