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

Rate this content

Documentation is essential to any project and it can really "make it or break it".  However documentation is time consuming to draft and can sometimes be forgotten, or updates and amendments to it left behind as the project moves forward.  Additionally, creating your documentation with Markdown has its limitations, so you may not end up with the result you want or that your contributor needs. 

By using MDX you can combine Markdown with code and integrate it into your React project.  Documentation becomes a more streamlined and efficient process and dare I say 

28 min
08 Dec, 2023

AI Generated Video Summary

Good documentation is crucial and can make or break a project. Word of mouth is important in the industry, and great documentation can attract users. MDX is a powerful tool for writing documentation, allowing for customization and reuse of components. Documentation should be treated like code, with testing and continuous improvement. Responsible AI usage is important, and a balanced approach to documentation, including inline comments and different formats, should be used.

1. Introduction to Docs with MDX

Short description:

Hello, React Day Berlin! Today, I'll be talking about Docs with MDX and how it can be a game-changer for your project. Good documentation is crucial, but not many people want to write it. Incorrect and outdated documentation frustrates me. Let's improve the numbers by the end of my talk. Docs are just as important as code. Remember, every pull request with code changes should also have tests and docs.

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.

2. Importance of Documentation

Short description:

Why is documentation important? Out-of-date documentation can be worse than no documentation. It can mislead users and cause frustration. Just like riding a bicycle with no brakes, documentation should be reliable. Missing steps in documentation can lead to errors and confusion. It's important to contribute to open source projects by reviewing and improving documentation.

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.

3. Importance of Documentation Continued

Short description:

So incorrect docs, hopefully that demonstrates that it's worse. Docs can make or break a project. Onboarding is really important. Word of mouth is so important in our industry. If you ask someone, 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. 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.

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.

4. Importance of Good Documentation

Short description:

And it is real and does exist. So I want to show one last real-world example. Your quick-start guide on your project is really important because it's the impression that people are going to get of your full documentation. Is there anyone here who wants bad documentation? So we don't want bad documentation. The developer experience of writing the documentation is bad. Is it in the same repo or do you have a separate workflow? If it's painful to do as developers, we're not going to do it. Documentation written by the author is only a good starting point. 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.

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.

5. Using MDX for Documentation

Short description:

I know I do, so we also have like a checkbox. You know, have I updated the documentation? Markdown is a lightweight markup language. MDX is a superset of Markdown and lets you write JSX within your Markdown files, which is so cool. MDX helped us achieve what we needed. It had that balance. We can customize the Markdown output. We can also reuse our Markdown files in multiple places. We can even reuse our components from the project. It's even possible to personalize the documentation.

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.

6. Using MDX for Documentation Continued

Short description:

Again, it's that developer experience. We see an image, inline code, bold, italics, quotes. We can combine them. This is what it will look like, very similar to the rest of our project. Eddie, what about Ascii Docs or Ascii Doctor? I love those tools. It's a lot for the team to learn. It's more difficult to integrate. What gets generated in the HTML is H2, H3, and a list. You can add additional functionality. This is a code block.

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.

7. Using MDX for Documentation (Part 2)

Short description:

MDX gives us a balance between familiarity and flexibility. Setting it up is straightforward. Install the MDX dependencies, create the mdx-components.js file, customize the HTML output, and configure Next.js to use MDX. Plugins like remark and rehype enable syntax highlighting, line numbering, and embedding social posts and charts.

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.

8. Using Front Matter and Testing

Short description:

You can use front matter and load remote content. Testing is a great tool, but not perfect. Have tests to check page loading and avoid errors. Treat documentation like code.

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.

9. Concluding Remarks and Call to Action

Short description:

Reward documentation just like code. Docs-driven development. Write the docs first. Connect with me on socials. Geek out with me. Thank you all for your engagement.

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.


Contributing to Open Source Documentation

Short description:

Thank you all for not falling asleep. Improving documentation is the best way to get into open-source and accelerate your career. Start by fixing typos and using your fresh pair of eyes. Make documentation review part of your workflow when reviewing pull requests.

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.

Importance of Responsible AI Usage

Short description:

We should treat documentation as part of our workflow and celebrate its importance. When using tools like AI, it's important to use them responsibly and not rely on them completely. During Hacktoberfest, AI was used to generate code and documentation, but it should be checked thoroughly for accuracy. AI is still in its early stages and should be used as a tool with human involvement.

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.

Inline Comments vs Documentation

Short description:

When it comes to inline comments versus documentation, I believe in using both. By copying and pasting a sentence or paragraph from the documentation and providing a link, developers can get a TLDR version and choose to read more if needed. Using a balanced diet approach, we should utilize different tools and formats for documentation. For example, MDX is a powerful tool that I'm excited to try out.

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.

Support for MDX in GitHub and GitLab

Short description:

Support in terms of the community is great, with lots of plugins available. However, when it comes to rendering MDX files in GitHub and GitLab, the code blocks don't look great. It would be better to direct users to GitHub pages or the deployed app for reading the documentation. GitHub is continuously adding more tools to their rendering, so it would be nice if they added MDX support to the readme page.

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.

Different Documentation and Code Preferences

Short description:

You come across different documentation, and there are some honorable mentions. Next.js documentation has simple and complex examples, except for the middleware. Balancing documentation is important. Readable code and great documentation are subjective. Get feedback from the community to improve. The documentation in BioDrop is praised.

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.

Value of Fresh Perspective and Proud of Biodrop

Short description:

There's value in someone new to the code or project providing a fresh perspective. Finding a balance between readable code and better documentation is important. The speaker is proud of the Biodrop project and the collaboration with the community in improving the documentation.

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.

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

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 Summit US 2023React Summit US 2023
32 min
Gateway to React: The Story
A behind the scenes look at the design and development of the all-new React docs at The new launched this year introducing new methodologies like challenges and interactive sandboxes and subtle inclusivity features, like "international tone" and culturally agnostic examples. Not only have the new docs changed how people learn React, they've inspired how we think about developer education as a community. In this talk, you will learn how the React team and some ambitious community members made the "React docs rock" for a generation of front end developers and how these new patterns and established techniques can be applied in your favorite projects.
React Finland 2021React Finland 2021
27 min
Opensource Documentation—Tales from React and React Native
Documentation is often your community's first point of contact with your project and their daily companion at work. So why is documentation the last thing that gets done, and how can we do it better? This talk shares how important documentation is for React and React Native and how you can invest in or contribute to making your favourite project's docs to build a thriving community
React Finland 2021React Finland 2021
18 min
Documenting components with stories
Most documentation systems focus on text content of one form or another: WYSIWYG editors, markdown, code comments, and so forth. Storybook, the industry-standard component workshop, takes a very different approach, focusing instead on component examples, or stories.
In this demo, I will introduce an open format called Component Story Format (CSF).
I will show how CSF can be used used to create interactive docs in Storybook, including auto-generated DocsPage and freeform MDX documentation. Storybook Docs is a convenient way to build a living production design system.
I will then show how CSF stories can be used create novel forms of documentation, such as multiplayer collaborative docs, interactive design prototypes, and even behavioral documentation via tests.
Finally, I will present the current status and outline a roadmap of improvements that are on their way in the coming months.
TypeScript Congress 2022TypeScript Congress 2022
25 min
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
Using real-life open-source examples, we'll explore the power of TypeScript to improve your users' experience. We'll cover best practices for library authors, as well as tips and tricks for how to take a library to the next level. This talk will cover: 
- how to leverage the type inference to provide help to your users; - using types to reduce the need and complexity of your documentation - for example, using function overloads, string literal types, and helper (no-op) functions; - setting up testing to ensure your library works (and your types do too!) with tools like tsd and expect-type; - treating types as an API and reducing breaking changes whilst shipping enhancements; - I'd draw on my experience with libraries like nuxt3, sanity-typed-queries and typed-vuex and show what we managed to do and what I'd do differently in future. 

React Advanced Conference 2021React Advanced Conference 2021
24 min
The Legendary Fountain of Truth: Componentize Your Documentation!
"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!