The Legendary Fountain of Truth: Componentize Your Documentation!

Bookmark

"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!

24 min
25 Oct, 2021

AI Generated Video Summary

Welcome to this session about documentation in a command-driven era. The Data Axis framework provides a comprehensive approach to documentation, covering different areas of the development process. Component-driven development and MDX syntax enable faster development, simpler maintenance, and better reusability. Embedding components in Markdown using MDX allows for more advanced and useful documentation creation. Tools like Storybook and Duxy with MDX support are recommended for documentation solutions. Embedding documentation directly within components and migrating to MDX offer a comprehensive documentation experience and open up new possibilities for embedding and improving documentation.

1. Documentation in a Command-Driven Era

Short description:

Welcome to this session about documentation in a command-driven era. Your documentation is the key to the success of your project. Keep your documentation associated with your code to avoid desynchronization. We need a single source of truth, which is your codebase. Keep the documentation in sync with the codebase and embed your codebase in 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.

2. The Data Axis Framework

Short description:

This is a documentation framework that many companies are using right now. It is oriented in four parts: READMES, O2s, FAQs, and main pages. READMES serve as the entry point for users, providing getting started guides. O2s are guides or recipes for working with specific parts of the project. FAQs contain discussions and histories, helping to understand project choices and interactions. Main pages provide advanced technical content. These four parts cover different areas of the development process.

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.

3. Component-Driven Development and MDX Syntax

Short description:

Component-driven development allows for faster development, simpler maintenance, better reusability, and better TDD. By isolating components in a sandbox environment, they can be easily maintained, tested, and documented. The Diataxis framework enables documentation to be organized around specific components, making it easy to understand their functionality and usage. MDX, a syntax that combines Markdown and JSX, allows for more advanced and useful documentation creation.

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.

4. Embedding Components in Markdown

Short description:

We now have components in Markdown directly. We can embed external components, pass props, and have TypeScript native support. MDX allows us to embed any kind of component using a flexible Markdown syntax. It's easy to configure MDX with different environments, from Gatsby to ReactStatic. Just add a single line of configuration.

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.

5. Documentation Frameworks and Solutions

Short description:

This is a documentation framework that provides tools for embedding MDX and creating proper documentation. It is useful if you are looking to produce documentation rather than just Macdon with components. Tools like Storybook and Duxy with MDX support are recommended for documentation solutions.

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.

6. Embedding Documentation in Components

Short description:

When working with components, it is essential to embed the documentation directly within the component itself. Backlight, a design system editor, allows for complete component-oriented development. Each component can have its own documentation, tests, and design tools embedded within it. MDX provides a way to import components directly into the documentation. Playground sandboxes and props tables are useful tools for rendering and customizing components in the documentation.

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.

7. Embedding Components and Migrating to MDX

Short description:

You can embed a single component as a reflector of your component and have access to all its properties in your documentation. MDX, combined with components, stories, playgrounds, and props tables, allows for a comprehensive documentation experience. Migrating to MDX is easy if you're already working with Markdown. Just organize your documentation using the ADDXS framework, isolate each component's documentation, and choose the right tool or platform. MDX is just the beginning of a new era with more formats and tools to embed and improve documentation. Focus on advanced DevTools and embedding code in documentation. DevRiot's tools, like webcomponents.dev and backlight.dev, offer comprehensive solutions for documentation and component-oriented development.

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.

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

React Advanced Conference 2021React Advanced Conference 2021
39 min
Don't Solve Problems, Eliminate Them
Humans are natural problem solvers and we're good enough at it that we've survived over the centuries and become the dominant species of the planet. Because we're so good at it, we sometimes become problem seekers too–looking for problems we can solve. Those who most successfully accomplish their goals are the problem eliminators. Let's talk about the distinction between solving and eliminating problems with examples from inside and outside the coding world.


JSNation 2022JSNation 2022
28 min
Full Stack Documentation
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.
React Advanced Conference 2022React Advanced Conference 2022
30 min
Using useEffect Effectively
Can useEffect affect your codebase negatively? From fetching data to fighting with imperative APIs, side effects are one of the biggest sources of frustration in web app development. And let’s be honest, putting everything in useEffect hooks doesn’t help much. In this talk, we'll demystify the useEffect hook and get a better understanding of when (and when not) to use it, as well as discover how declarative effects can make effect management more maintainable in even the most complex React apps.
React Advanced Conference 2021React Advanced Conference 2021
47 min
Design Systems: Walking the Line Between Flexibility and Consistency
Design systems aim to bring consistency to a brand's design and make the UI development productive. Component libraries with well-thought API can make this a breeze. But, sometimes an API choice can accidentally overstep and slow the team down! There's a balance there... somewhere. Let's explore some of the problems and possible creative solutions.


React Summit 2023React Summit 2023
24 min
React Concurrency, Explained
React 18! Concurrent features! You might’ve already tried the new APIs like useTransition, or you might’ve just heard of them. But do you know how React 18 achieves the performance wins it brings with itself? In this talk, let’s peek under the hood of React 18’s performance features: - How React 18 lowers the time your page stays frozen (aka TBT) - What exactly happens in the main thread when you run useTransition() - What’s the catch with the improvements (there’s no free cake!), and why Vue.js and Preact straight refused to ship anything similar

Workshops on related topic

React Summit Remote Edition 2021React Summit Remote Edition 2021
177 min
React Hooks Tips Only the Pros Know
Workshop
The addition of the hooks API to React was quite a major change. Before hooks most components had to be class based. Now, with hooks, these are often much simpler functional components. Hooks can be really simple to use. Almost deceptively simple. Because there are still plenty of ways you can mess up with hooks. And it often turns out there are many ways where you can improve your components a better understanding of how each React hook can be used.
You will learn all about the pros and cons of the various hooks. You will learn when to use useState() versus useReducer(). We will look at using useContext() efficiently. You will see when to use useLayoutEffect() and when useEffect() is better.


React Advanced Conference 2021React Advanced Conference 2021
174 min
React, TypeScript, and TDD
Workshop Free
ReactJS is wildly popular and thus wildly supported. TypeScript is increasingly popular, and thus increasingly supported.
The two together? Not as much. Given that they both change quickly, it's hard to find accurate learning materials.
React+TypeScript, with JetBrains IDEs? That three-part combination is the topic of this series. We'll show a little about a lot. Meaning, the key steps to getting productive, in the IDE, for React projects using TypeScript. Along the way we'll show test-driven development and emphasize tips-and-tricks in the IDE.


React Summit 2023React Summit 2023
171 min
React Performance Debugging Masterclass
Workshop Free
Ivan’s first attempts at performance debugging were chaotic. He would see a slow interaction, try a random optimization, see that it didn't help, and keep trying other optimizations until he found the right one (or gave up).
Back then, Ivan didn’t know how to use performance devtools well. He would do a recording in Chrome DevTools or React Profiler, poke around it, try clicking random things, and then close it in frustration a few minutes later. Now, Ivan knows exactly where and what to look for. And in this workshop, Ivan will teach you that too.
Here’s how this is going to work. We’ll take a slow app → debug it (using tools like Chrome DevTools, React Profiler, and why-did-you-render) → pinpoint the bottleneck → and then repeat, several times more. We won’t talk about the solutions (in 90% of the cases, it’s just the ol’ regular useMemo() or memo()). But we’ll talk about everything that comes before – and learn how to analyze any React performance problem, step by step.
(Note: This workshop is best suited for engineers who are already familiar with how useMemo() and memo() work – but want to get better at using the performance tools around React. Also, we’ll be covering interaction performance, not load speed, so you won’t hear a word about Lighthouse 🤐)
React Summit 2023React Summit 2023
152 min
Designing Effective Tests With React Testing Library
Workshop
React Testing Library is a great framework for React component tests because there are a lot of questions it answers for you, so you don’t need to worry about those questions. But that doesn’t mean testing is easy. There are still a lot of questions you have to figure out for yourself: How many component tests should you write vs end-to-end tests or lower-level unit tests? How can you test a certain line of code that is tricky to test? And what in the world are you supposed to do about that persistent act() warning?
In this three-hour workshop we’ll introduce React Testing Library along with a mental model for how to think about designing your component tests. This mental model will help you see how to test each bit of logic, whether or not to mock dependencies, and will help improve the design of your components. You’ll walk away with the tools, techniques, and principles you need to implement low-cost, high-value component tests.
Table of contents
- The different kinds of React application tests, and where component tests fit in
- A mental model for thinking about the inputs and outputs of the components you test
- Options for selecting DOM elements to verify and interact with them
- The value of mocks and why they shouldn’t be avoided
- The challenges with asynchrony in RTL tests and how to handle them
Prerequisites
- Familiarity with building applications with React
- Basic experience writing automated tests with Jest or another unit testing framework
- You do not need any experience with React Testing Library
- Machine setup: Node LTS, Yarn
React Day Berlin 2022React Day Berlin 2022
53 min
Next.js 13: Data Fetching Strategies
Workshop Free
- Introduction
- Prerequisites for the workshop
- Fetching strategies: fundamentals
- Fetching strategies – hands-on: fetch API, cache (static VS dynamic), revalidate, suspense (parallel data fetching)
- Test your build and serve it on Vercel
- Future: Server components VS Client components
- Workshop easter egg (unrelated to the topic, calling out accessibility)
- Wrapping up
React Summit 2022React Summit 2022
160 min
React at Scale with Nx
Workshop Free
The larger a codebase grows, the more difficult it becomes to maintain. All the informal processes of a small team need to be systematized and supported with tooling as the team grows. Come learn how Nx allows developers to focus their attention more on application code and less on tooling.
We’ll build up a monorepo from scratch, creating a client app and server app that share an API type library. We’ll learn how Nx uses executors and generators to make the developer experience more consistent across projects. We’ll then make our own executors and generators for processes that are unique to our organization. We’ll also explore the growing ecosystem of plugins that allow for the smooth integration of frameworks and libraries.