How MDX is a game changer for your React Project's Documentation

Thank you so much for that warm welcome. Well, hello, React Day Berlin. My name is Eddie Chow and I'm super excited to geek out with you today on Docs with MDX and how it can be a game-changer for your project.

We all want good documentation, but it seems that not many people want to write it. I get frustrated when docs don't exist. And I also get frustrated when they have a hello world example. I want a real-world example. But you know what really, really gets me? When the documentation is incorrect and out of date. And unfortunately, it happens too often. And let me just clarify, by good, I just mean correct, up to date, and it looks nice. I don't think that's too much for us to ask.

I mean, who likes reading good documentation? Let's have a show of hands. I mean, hopefully, most of us. Great. Thank you so much. Great to see you all awake as well. Like I said, nothing fancy, it's what we expect. I mean, who likes writing documentation? Okay, a few people, some people unsure. Okay, well, hopefully, we can improve those numbers by the end of my talk.

Docs are just as important as code. And if there's one thing you take away from this entire talk, please remember that. We might not treat it like that, though. We don't get the same buzz. And also, we don't get the same street cred from our peers as well. When someone says, I wrote this cool feature, I used library X, and everyone's like, oh yeah, great. And if someone says, I documented feature X, literally silence, you don't get that same street cred. And I think that has a role to play as well. But hopefully, we can all agree that documentation is important, and it's our responsibility to have good documentation. Tests are also really important, but that's a separate discussion, and we did chat about that yesterday here at TestJS. So I believe every pull request that has code changes should also have tests and docs as well.

Why? Because everything should be reviewed. What is worse than no documentation? Yes, there is something worse than no documentation. Out-of-date documentation. Why? Because people trust it. So when something goes wrong, it's even more painful. We're guiding people down the wrong path, so no docs can actually be better. People know to go look at the code, or try and figure it out, or phone a friend.

Have you ever ridden a bicycle with no brakes? I actually have. Earlier this year in Bangkok, we're at a hotel, we want to go to the park, and they said, you know, we can borrow our bikes. But they have no brakes. But because we knew it had no brakes, we went slower. I made sure Sarah went in front, so I could use her to stop. No, I'm just kidding. But if a bike has brakes, you expect them to work. And the same with documentation.

I mean, how many of you have seen this before? I'm sure you've seen this a lot of times. My core project, and then no documentation. That's one scenario. Another scenario is docs with missing steps. Hopefully some people can shout out what the two steps are missing here. Yes, so before install dependencies, navigate into the new directory that was created by the Git clone, and then install dependencies, and then run npm run dev. There's nothing wrong with this. This isn't incorrect. It is just missing some steps. If someone gets an error on that second step, and Googles it, they're probably going to get, you know, try and install dependencies. Okay, package.js is not found. Right, navigate into the directory, install dependencies. And they'll get there because this is great. And by the way, you'll see this on so many open source projects, so it's a great way to contribute is to go through the documentation and don't make any assumptions because if you're familiar with projects like this, then you'll know what commands to run. But people who are new to tech or new to the project won't.

So it's a great way to get into open source. This is a really crude example, so just take it with a pinch of salt. But it has the two missing steps from the last example, but the last step is incorrect. And I've actually seen this on a project. And it's interesting to what people try. They might put sudo in front of it to see if that helps. But when they Google that fourth command, they're going to get run npm run build. And then this command is going to work. The problem is they haven't solved the problem. They've just got it working for now. But when they make code changes in development environment, this isn't going to work. They're not going to see the reload, and they're not going to see their changes.

So incorrect docs, hopefully that demonstrates that it's worse. So if docs are so important, why are they not treated as importantly as code? Docs can make or break a project. I've seen projects do well because of good documentation. And I've seen really, really good projects do badly because of bad documentation. Onboarding is really important. It's the first impression that someone gets of your project. It is their first experience. And word of mouth is so important in our industry. If you ask someone, you know, what library should you use? And they said, well, this library is really lightweight, really fast. Oh, it's terrible to use. It took me hours or days to get set up. You're probably not going to give it a try, let alone use it in your project. Where if someone said, it's a bit of a big project, it's a bit bloated, but the documentation is great. You can get up and running in minutes. I guarantee you, you're going to give it a try, and you'll probably end up using it for a lot longer. So word of mouth is really, really important. I mean, have you heard of DX, Developer Experience? I'm guessing we have. Perfect.

And it is real and does exist. So I want to show one last real-world example. So which one would you prefer to get into? Let's imagine you're dressed nice and smart to come to an awesome conference like React Day Berlin, and both these cars pull up. Ignore that the car on the right is German. You know, we won't have any bias to awesome German cars, but the one on the left pulls up, you're going to assume you're going to get dirty when you get in, or inside is probably dirty, whereas the one on the right, you think you've got air conditioning or heated seats. It's going to be really nice.

And so your quick-start guide on your project is really important because it's the impression that people are going to get of actually your full documentation. So we all want good docs. And just one last question, is there anyone here who wants bad documentation? So someone raised their phone to take a picture, but I thought they were raising their hand. I was like, I wasn't expecting that. Okay, perfect. So no one wants good documentation. So someone wants bad documentation.

So we don't want bad documentation. And when I say we, I include myself in this. Why don't we write good documentation? I think it's because the developer experience of writing the documentation is bad. So if we take a step back before having good documentation, and we need to write good documentation, and that experience is really important. So I mentioned DX from the perspective of consuming documentation. Let's look at it from writing documentation. I think that's even more important. Is it in the same repo or do you have a separate workflow? Like is it in a separate wiki where you have to submit your PR, it gets merged in, and then you have to think about documentation later on? I mean, let's face it. If it's painful to do as developers, we're not going to do it. I mean, that's why our Jira tickets never get updated. You have to log into another platform, and yeah, you know the story. I mean, does it use Markdown, or does it use a drag and drop WYSIWYG or another technology? I think this is what we need to do in our projects to make it a lot better. A single workflow where a pull request contains docs and tests, and plus, let's face it, documentation written by the author is only a good starting point. It's never going to be the best documentation because we make assumptions, as we saw earlier on. We miss steps, and so therefore, it can get reviewed. People can ask questions, and we can make it better. We do forget to include documentation, even if it is in a single workflow.

I know I do, so we also have like a checkbox. You know, have I updated the documentation? It's not bulletproof, but it does help us remember when we create a pull request to check and give it a tick, and if we don't give it a tick, maybe the person reviewing will also think to check, well, you have an updated documentation.

Maybe you should with these code changes. Markdown. Markdown is a lightweight markup language. You all know that. I'm sure you use it all the time. I think it's great. I think it's awesome. We use it on GitHub issues and comments and pull requests. We all love Markdown. People even write blogs with it, but it has its limits. This is where MDX comes in.

MDX is a superset of Markdown and lets you write JSX within your Markdown files, which is so cool. So I found that MDX helped us achieve what we needed. It had that balance. We can customize the Markdown output. You know, lots of libraries do that. That's great. It's really easy to use, I think. We can also reuse our Markdown files in multiple places. So you can link to a separate page, but maybe a small bit of Markdown documentation doesn't require its own page. So you can import it and include it in your other Markdown files, which is awesome. We can even reuse our components from the project. So we can make it look similar. Our documentation will look very similar to our actual project. We can loop over data from our config file, expose session data or environment variables, hopefully nothing secret. But you get the idea. It's even possible to personalize the documentation. So if some documentation is saying, I don't know, you need to call this bit of code with your project ID, you can actually put their project ID or whatever ID in the documentation, which I just think is super, super awesome.

Again, it's that developer experience. I mean, this is Markdown that you're all familiar with. We see an image, we see inline code, bold, italics, quotes. I mean, you're all familiar with this. We're a React conference, so you're all probably familiar with this as well. I see a few people nodding.

Awesome, I'm not gonna go through it. But we can combine them. So now we have the two hashes, which is our H2 in HTML, gets converted. And then we have our alert component from our project. We haven't made this alert component specifically for our documentation. This is an alert if we get a form submission incorrect or whatever it is. So, and then we've got more Markdown. So it is super, super consistent. And this is what it will look like. And you'll see it's very similar to the rest of our project.

I know what some of you are thinking. Some of you who have spent a bit of time in the documentation world will be thinking, Eddie, what about Ascii Docs or Ascii Doctor? I love those tools, by the way. They are absolutely awesome. However, it's a lot for the team to learn. It's a whole other kind of markup to learn. And it's got lots of functionality. People write books with it. It's great. But the onboarding process for the team is a lot more difficult. And also I found it's a lot more difficult to integrate into the project directly as well. And again, just to prove it to you that what gets generated in the HTML, the output, it's H2, H3 and a list and so forth. So nothing too fancy. So I want to mention that not only including components, but you can add additional functionality. So this is a code block.

We've used our triple backticks, maybe added JSON at the top at the end of the three backticks to give a syntax highlighting. But what do we notice? We notice at the top right is a copy button. So we can actually add functionality to our documentation as well. So I feel MDX gives us that balance between what we're familiar with and also flexibility as well.

I know what you're thinking. How difficult is it to get set up? I want to give it a try today. Well, if you take one minute out of your lunch break, you could give this a try. You could create a new Next.js project or you could add it to your existing Next project or React project or any other project for that matter. Really straightforward. You install the MDX dependencies for the library or framework that you're using. And then for the Next.js project, you need in the root of the project, mdx-components.js. And in this example, we're just returning the default HTML that gets generated from the markdown, and we're going to customize that shortly. And then we've got our Next.js config to use with MDX. I did mention about customizing it. So with that file, that component that's in the root of your project, you can see here, we've customized the H1 and the image. And it's really straightforward. It's syntax that you're already very familiar with. This is a real-world project. So the reason why I'm showing you this is on the left, you can see the code to generate this page on the right. And if you look at the bottom on the left, you'll see it has layouts. So now on the right, before I was just showing you the actual output, but you can see the full page, we've actually got navigation. So now, again, it's included in our project. It's treated just like code, and to the user, it also looks part of the project as well.

Okay. So plugins. There are so many plugins you can use with MDX. And we all love plugins, right? We add loads of plugins to all our projects, like remark, rehype. What do these things do? They do syntax highlighting for your code blocks. You can do line numbering. You can embed social posts, charts.

You can even use front matter. That's where, for those of you who've used Jekyll before, you can put the, like, the YAML config at the top as well. I mean, you can even load remote content. Obviously, you need to be a bit careful in terms of security, but you can do that as well.

I mentioned testing earlier before. I want to briefly touch on it again. Some challenges. So it is a great tool. I highly recommend using it, but it's not perfect. Nothing ever is. Make sure you have tests that just check that the page loads on all your documentation. Just check that the title appears and there's no error. I found sometimes some VS Code plugins, when you hit save on those files, it gets a bit confused. You might add three extra back ticks. There's a bug I had recently. I don't know why, at the bottom of the file. So just check that they load and it doesn't break.

So at the end, you usually say conclusion, takeaways, et cetera. To be honest, I want to say this is the beginning. Maybe it's the beginning of docs-driven development, DDD. Okay. DDD has been taken. We'll workshop that. We'll work on it. But docs are really, really important. And the developer experience of writing documentation, I think is even more important. I recommend keeping docs in the same repo. Have pull requests. Have those documentation changes as well. Treat docs like code.

Reward it just like code as well. I love bad docs. Was never said by anybody. So you'll never hear that. Docs-driven development. Why not write the docs first? I will leave you with that thought.

If any of you want to geek out with me, please. I love questions. Ask me questions at the end or afterwards. If you want to connect with me on socials, this is my Biodrop QR code. You can get my YouTube, Twitter, Eddy Hub that was mentioned earlier as well. I'm full-time on the open-source project. Biodrops, you want to geek out with me? I know Julia helps me with accessibility and has done some amazing pull requests. So thank you so much, Julia, as well. But yeah, come and geek out with us. Thank you so much, everyone, for not falling asleep.

Thank you so much, everyone, for not falling asleep. Thank you. I love documentation, and I love what you talked about, especially at the start. You got everyone to raise their hands like, who likes reading good docs? Yay! Who likes writing docs? There's lots of people. Everyone knows that we need good docs. But sometimes maybe they come across they're working on an open-source project or with an open-source project, come across some documentation that is lacking. And people want to make it better. At least I've been in this position before, but it's intimidating knowing that, like, do I have the experience? Am I just going to put documentation for someone else to come slap it down and be like, it's not good enough? But how can people sort of get into that, start to contribute to those projects? I mean, the best way to get into open-source and to network with awesome people and accelerate your career, as in the talk I have, is to improve the documentation. If you're new to a technology or a project, you have an advantage. You have a fresh pair of eyes. You're not going to make assumptions. You're going to go through it step by step and check if things work or things are out of date. I mean, let's be honest, my first open-source contribution was contributing to documentation. I fixed a typo. And if we're really being honest, I think we're all friends here, my 10th contribution was also fixing a typo as well. But that's how we all start. So I highly recommend it. And like I said, your fresh pair of eyes can add so much value. I will say I have fixed the typo, but I remember one time I fixed the typo that was in British English. And then it got flipped back and I was like, yeah, I deserve that. I deserve that. That was early in my open-source career. But yeah, let's jump into some of the questions that have come from the audience. You got it down there if you want to read it as well, which are, what are some of the tips to keep documentation up to date? That's the thing you talked about, which is one of the worst case scenarios, like documentation that is incorrect. So maybe out of date or something. So what are some tips for people to keep it up to date? I see in some of the questions, AI and so forth, AI consumes our documentation. So we need to keep it up to date. That's really important. I think the tips are to make it part of your workflow when you're reviewing pull requests. I think that's really important.

And we need to celebrate documentation being up to date and not being an afterthought. There aren't any magic tools. I have tried various things and they're okay. They're still under review. So maybe let's chat in a few weeks or a month. I have had some people reach out recently and say, oh, have you tried this tool? So I'm exploring it. I don't think there is a magic wand that you can wave. I think it just needs to be treated just like our code changes as part of our workflow, and we should celebrate it hopefully as well.

For sure. And I know you kind of touched on this as well, because I think a lot of people, when they want to use tools like AI, they want to have a fire and forget. Like, oh, I've put it and I don't need to think about it. So obviously that's not the right way. Are there maybe any ways that people can use it, but in a safe way that doesn't just, that isn't irresponsible, I would say.

True. I would say, try it. During Hacktoberfest in October, when people were contributing to open source, people used AI a lot to generate code, documentation, but they never actually checked it. And I think if they just went through the documentation that they generated and just read it, tried the commands, they'd see that maybe there was some missing steps or maybe there was a version mix up with the tool that they were using. So I would just say, go through it and check it. Or you could ask a friend to do it if they don't mind. Yeah, I would ask a friend. I think it's just having that, again, that fresh perspective from somebody else. But if you keep doing it all the time because you're not checking it yourself, I'll definitely check it yourself, then get a second opinion afterwards. Yeah, for sure. I don't think it's reliable just yet, so you've got to wait for it to, and also it's like a baby, right? You're not going to be like, oh, you've learned to walk. All right, go run 100 meters now. You're going to walk around, hold a baby's hand. And I think at least right now, AI is definitely in that space. It's a tool you can use, but you still need to be a part of that process.

All right, so now this is kind of going into so much semantics and the different approaches to docs. There's a versus.

I'm pretty sure a lot of your answers are about to be it's depends, but let's go into them. So one of them is about inline comments versus documentation. Like, what do you think about that? So let me just clarify. So inline comments, we're talking about pull requests and then documentation. We're talking about, what, directing someone to the documentation and saying this can be read here. If that's the case, and if it isn't, I get it wrong, I'm sorry. Come and chat to me afterwards and we can dig a bit deeper.

But I would say both. And what I mean by that is, copy and paste that one sentence and one paragraph from documentation and then put a link and just say, if you want to read more, go and here's the full documentation. I think that as developers, we all love that TLDR. I guarantee you, they probably won't go read the full documentation unless they're stuck or they really need to. So that one line, I think we'll try and reduce that back and forth. I mean, for my YouTube videos, I had someone say, I saw you've got a 10-minute YouTube video on this. Can you summarize it for me into like two lines? I was like, it's already a summary in a 10-minute video. It's edited really quickly. So yeah.

No, totally. And I think there's a part of that as well, which is to use all the different tools as well. It's not like one or the other. It's a balanced diet. Like you want to have different things in your diet and you want to have a balanced diet of documentation. I love that example. I gave a talk called The Balanced Diet of Documentation. Proud, proud of it. All right. So let's move on. And this is more about MDX. I seem to love it. I've never used MDX, but it looked amazing and I want to try it out. And this person's question is also my question.

What's the support for it in GitHub or GitLab or where people are already using Git? So support, I guess, can be taken in two ways. So I'll give two answers. So support in terms of the community, I think it's great. I haven't had any issues. Like I said, there's lots of plugins. And if I have had issues, I've put a question like, I can't remember, I think I did it on Discord and someone replied. But in terms of support, in terms of, if you put, because our MD files are rendered in GitHub and GitLab. MDX is and isn't. So you get to see the code blocks. It doesn't look great. So the support in terms of, I wouldn't direct someone to read the documentation on GitHub in the MDX file. It would be like GitHub pages or the deployed app or something like that. It hasn't got that far yet. But I know GitHub are always adding more kind of tools to their rendering. So maybe we should shout out GitHub to add like MDX just on, read me when you hit the page. That would be quite nice actually.

All right. And you come across like so many different documentation. You probably have a few, like, I won't, let's not say one, you're the best single docs, but maybe there are just some few honorable mentions that you think these people do this really well. People do something else really well. That's a really good question. Sorry. Yeah. Really good question. And you put me on the spot. That's a tough one. I would say Next.js, their documentation, they do have like some simple examples. If you just want to get started, something working, but then they have like, if you want something more complicated, like all the configuration, like the fully fledged real life examples, apart from their middleware, I was doing some custom domain stuff on Vercel and Next.js and their middleware. It was like, I don't know, 20 lines of code. And it took me like three weeks to get it working. And I did a video on it because I was like quite frustrated. Like it's actually, you could code this in like 30 minutes, but so much back and forth. So apart from that area, because I don't think many people use the middleware for sub-domains for multi-tenancy apps. So apart from that, the rest of the documentation is really good. You need balanced of documentation. And also when you see a holding documentation, you document it as well, so that other people can learn from it.

All right, now this is another, I'm guessing it's going to be an interpens question, but someone's asked like readable code with maybe good comments and other things, but not much documentation. Do you prefer that over complex code and great documentation? I have a theory. I think that lots of different people give different answers to this, depending on their style, but what's your answer? And then what would you recommend to others? I think, you know, readable code is very subjective. I think complex code and great documentation is also subjective. I would say get feedback from the community and you can improve it, right? When I submit a pull request or give a talk, I'm not saying this is the perfect pull request or the perfect talk. I'm there to start that feature and maybe get MVP out to the users or start the conversation in a talk. We keep iterating and improving. If you look at the documentation in BioDrop, people do say great documentation. It's not because of me. I started it.

There's probably like a thousand contributors to those files. And what I say to people in the community to improve that, to have the readable code, to have the better documentation, when someone's new to the project, they say, oh, can you tell me about the project? Tell me about documentation? I want to learn more about it. And I'm like, no. Can you tell me about the project and about the code? And if you can't, there's nothing wrong with you. There's something wrong with our project. But with your help, with your fresh perspective, we can improve it. And that's how we've iterated it and made it better. So that's where I think the value from someone new to the code or the project can really, really help. So I would say find a balance. It's a tough one. Maybe we can discuss that more afterwards. I'd be interested to know some examples.

No, for sure, for sure. I know there are so many more questions than the time we have. So if we don't get to your question, remember to come and find him and you'll be able to ask your questions in person. And a question that I kind of want to ask is kind of one of the questions that we had before, but I want to rephrase it. What documentation, this will be the last one, what documentation are you most proud of that you've worked on that you are most proud of and why? I love this question. And I would say Biodrop because this is like, I think my 200th open-source project, but it's the one where I've had people in tech, you know, review the docs, improve it. And also people not in tech, designers, lawyers, other people go through the documentation. So I think, again, it's not perfect. There's still room for improvement, especially as the code has moved forward and so forth. But I think we've got a really good foundation. So I'm really proud of what the maintainers and the community have done for the Biodrop project. And in true community fashion, he's not proud because he did it, but he's proud because so many other people worked with him on the journey. Thank you for allowing us to be a part of your journey, Eddie. Thank you so much. Thank you. I really appreciate it.