The Legendary Fountain of Truth: Componentize Your Documentation!

Hi everyone! Nice to have you here! Welcome to this session about documentation in a command-driven era. So we're gonna 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 gonna have a single clue about how is it working and how you are supposed to use your project or use any part of your project. So you have to keep your documentation properly associated with your code. Fact is living documentation is a pain today just because if you have to duplicate your code from your codebase to your documentation, you obviously leads to a desynchronization at some point of your documentation versus your codebase. 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 to keep things organized between your documentation and your codebase. We tried things like storybook, we tried things like ambed, 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 codebase 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 leave and this is directly in your codebase. So we do have to do something to keep the documentation in sync with the codebase and we do need something to embed your codebase in your documentation level.

So just a reminder about the data axis 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 READMES. READMES are the entry point of your documentation. When a user is coming to your new documentation and don't have any clue where to start, the READMES are the correct entry point. There are something like getting started guides, this kind of stuff. Something where you can re-play 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 O2s. The O2s are more guides or recipes and they are dedicated at how you want to work with this part of the project or how can I embed my project in a React app, how can I use my library with this kind of back-end and so on. 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.

Third part are the FAQs. In them 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. This is a comprehensive guide of particular deep technical content. These four parts are attached to four different areas. Readmes and O2s are the practices points. Each time you are asking, OK, I'm working on a new part of the documentation, and I want to add some new content in it, which topic it is 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 Hotos, this is practice, where the packs and the main pages are more dedicated to understanding the project and the basis 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 Hotos are more dedicated to... And the main pages are more dedicated to where... When I want to use the project, which part do I have to keep an eye on? Is it on the Hotos? 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 Attacksys 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 document... In a component-driven development area.

So, in this environment, I'm working on components more than any other parts. And so, this component-driven development brings us a new way to develop and to think our application, because it involves a faster development, a simpler maintenance, better reusability, better TDD, because every part of your application is separated in small parts, in small components.

And when you split your whole frontend interface in components only, then you are able to work on small 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? That 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 what is it working like that, how is this component is 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 or 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 these particular parts of my applications 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'm looking for a new documentation on a project, what I am looking for is OK, 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 Visual Effects, 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 component that is probably 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 document, this component in our documentation, play with it and just try it, test it, have some kind of experiment, break it at some point. But this is not, it is just because you could use your component in a dedicated area that is a live in 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 in 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 embed 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. 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 a linear from Markdown to HTML, but this is from Markdown to JSX to HTML. So 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 step, 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. This is just a process of different conversion. 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.

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. 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 relab config. 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 ReactStatic to whatever you want. I just have to embed my MDX configuration in my Webpack or relab, 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 a documentation working.

This is really, really handy if you just want to produce a Macdon 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 layout, proper props table, proper playgrounds, and so on. This is solution like Storybook with native support of MDX pages or Dubbd. It comes with more constraints because this is a documentation framework, but this is really useful is what you are looking for is producing documentation and just not producing Macdon with components in them. If you are looking for a documentation solution, I do encourage you to have a look on documentation tools oriented like Storybook, Duxy and so on, with MDX native support in them. Because they are giving 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, you have to embed everything in them. This is the backlight view.

Backlight is a tool that we are working to at DivRiots. This is a design system editor. So it's totally component oriented. Each part of the interface of separation of concerns is 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 component, finally. 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 Maldon with GSX support, in Madinx, and with this MDX syntax, I could import my button directly in my documentation. Let's see how.

So, we have GSX component. They run in isolated environment, that is reacting on the wrapping environment of our component. So, I just want to embed everything in the same way. So, how to work with them with your home playground. The fact is, MDX is too low level. We 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 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 components are supposed to work. So this is a kind of reflector for component properties. This is auto-built with any kind of properties that I could expose from my component. So this is up to date because all I have 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 can 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're working in documentation and you could embed any kind of elements related to this component description, the playground, the props table, everything will be in a single line aligned with my code because the documentation is not decorated for my components right now, it embeds my components in it.

So finally, MDX plus components, stories, format, plus playgrounds, plus props table, poms! 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 MacDon format. So you don't have to adapt anything. You just have to organize your documentation from the ADDXS framework to your different components. So I have it properly isolated each documentation to each component at the side. Then you could pick your ride 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 and 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're looking for. You do have now to focus on advanced and integrated DevTools 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 on in DevRiot backlight of webcomponents.dev.

If you have any questions, we will meet in a Q&A session right now. For everything else, thank you very much. I'm Mats, a participatory developer advocate at DevRiot, where we're working on document and components-oriented solutions like webcomponents.dev or backlight.dev that are design-systems-oriented IDE in your browser, directly in your browser with anything you need in it, like documentation process, MDX, playgrounds, props, tables, and so on, have a look at them.