Smoothly Inclusive Component Library Documentation

Rate this content
Bookmark

Is your complex documentation setup a maintenance nightmare and chasing away potential contributors? In this talk, you will learn how to make your React component library documentation more user and contributor-friendly with Gats and MDX. Pair this with accessibility best practices, and your documentation will be inclusively smooth.

18 min
17 Jun, 2021

AI Generated Video Summary

This Talk discusses how Gatsby and MDX can improve component library documentation. The speaker shares their experience with a previous design system and the challenges they faced with documentation. They explain how Gatsby was chosen as a solution and the benefits it provided. The use of MDX is highlighted as a way to enhance component documentation. The addition of editable code blocks is also mentioned as a means to make the documentation more interactive and intuitive.

1. Introduction to Component Library Documentation

Short description:

Hello, my name is Kathleen McMahon and I'm here today to tell you how Gatsby and NDX make your component library documentation smoothly inclusive. Before we begin, let's get some details out of the way. My slide deck will be posted on Noticed including links to resources that I briefly touch upon. Before we dig into GaspianMDX, let's back up a bit so I can introduce myself a little bit better. I'm a principal engineer at CarGurus and I race bikes, very badly. Before CarGurus, I was a tech lead for the O'Reilly Media Design System. In our case, our focus was to extract the business logic out of our components and get the accessibility in. We fixed our colors, our components, our patterns, and rebooted our docs. Once that was done, we realized that part of our system was becoming a hindrance to our team and a barrier to entry for our contributors, our documentation. Our process was spread across two projects, the design system repo and the design system docs repo. Just getting started working with these repos was overwhelming for new contributors to say the least. The scripts were set up in such a way that you had to write your markdown in a very specific order for your component and your content to show up in the docs. So while our docs scripts were great for generating color swatches and details about which props were available in components, the process was not great for creating our component documentation which frustrated everyone. One mistake and if not whole chunks of documentation would be missing from the component pages. We had the freedom of using markdown yet we were not taking advantage of it.

How to Develop your Web App Connect with other web developers How to develop your web app Create a website How to create a website How to create a website How to create a website Create a website How to create a website How to create a website How to create a website How to create a website

Hello, my name is Kathleen McMahon and I'm here today to tell you how Gatsby and NDX make your component library documentation smoothly inclusive. Before we begin, let's get some details out of the way. My slide deck will be posted on Noticed including links to resources that I briefly touch upon. The full URL will be available later today on Twitter. But for now, if you want to download, if you want to take a look, you can look at https://noti.st r-e-s-o-u-r-c-e-1-1 You can also find me at resource11 on Twitter, Instagram and GitHub.

Before we dig into GaspianMDX, let's back up a bit so I can introduce myself a little bit better. I'm a principal engineer at CarGurus and I race bikes, very badly. Mostly, you'll see me in costume racing two laps to your six at the back of the pack on a single-speed bike, mostly, unless something happens, like a pandemic kicking in our doors. Then, your racing season is postponed. So, while I'm an engineer and a super slow bike racer, I am a super fan of design systems, especially the component library parts. Before CarGurus, I was a tech lead for the O'Reilly Media Design System. While I was there, I learned a lot about streamlining component libraries and optimizing documentation. If you've never worked on a design system before, let's just say there are a lot of moving parts. And if your core team is small and you are rebooting your component library, you really have to choose your focus and rely on your contributors. In our case, our focus was to extract the business logic out of our components and get the accessibility in. We fixed our colors, our components, our patterns, and rebooted our docs. Once that was done, we realized that part of our system was becoming a hindrance to our team and a barrier to entry for our contributors, our documentation. Our process was spread across two projects, the design system repo and the design system docs repo. In the design system repo, the documentation content was stored in two locations while the docs repo held the site scaffolding and the docs layout components. To get up and running, you had to follow a detailed series of steps to sync, run scripts, grab files, parse information, generate data and render the docs into a React app. Ooh, that's a lot. Just getting started working with these repos was overwhelming for new contributors to say the least. But wait, there's more. The scripts were set up in such a way that you had to write your markdown in a very specific order for your component and your content to show up in the docs. Your button heading could be paired with an intro paragraph but only one paragraph. Same with the variance, only one paragraph and then a code block. Best practices had to be written as an unordered list, always, same with the related components section, always and an ordered list. So while our docs scripts were great for generating color swatches and details about which props were available in components, the process was not great for creating our component documentation which frustrated everyone. One mistake and if not whole chunks of documentation would be missing from the component pages. We had the freedom of using markdown yet we were not taking advantage of it.

2. Improving the Documentation Process with Gatsby

Short description:

This was a serious cognitive lift even for someone who was very familiar with the code base. We decided to review our process what wasn't working. One of our biggest issues, we chose to show one component variant at a time rather than all at once. This forced our users to access a select menu over and over again to compare component variants which increased the time they needed to look up information. It didn't make sense. So we decided it was time to make our docs contribution process more user-friendly in terms of structure and in terms of how we authored. We considered our options for making our docs better and decided upon Gatsby for a few reasons. One, Gatsby gave us a way to migrate all our main documentation pages right into the site without much fuss. Two, Gatsby provides a web pack and Babel config similar to Create React app, so we could start with a scaffolded project and extend as needed. And three, Gatsby supports MDX, so we could write component documentation using Markdown, import React components right into the file, and it just works even better. MDX compiles down into semantic HTML, which in turn gives the site improved accessibility. As a bonus, Gatsby, we streamed our stuff from two repos to one and reduced the amount of CLI commands dramatically. However, we needed to make some adjustments so Gatsby worked for our needs.

This was a serious cognitive lift even for someone who was very familiar with the code base. Now imagine, if you have a new contributor to your project, not exactly welcoming experience.

We decided to review our process what wasn't working. One of our biggest issues, we chose to show one component variant at a time rather than all at once. This forced our users to access a select menu over and over again to compare component variants which increased the time they needed to look up information. It didn't make sense. In retrospect, that decision was about as questionable as a recipe that combines Jell-O with shellfish.

So we decided it was time to make our docs contribution process more user-friendly in terms of structure and in terms of how we authored. Especially the component example pages. We wanted the users to have the confidence that whatever content they wrote on the docs page would make it into that docs page. If we made our docs more user-friendly, we'd have more contributors rather than fewer.

We considered our options for making our docs better and decided upon Gatsby for a few reasons. One, Gatsby gave us a way to migrate all our main documentation pages right into the site without much fuss. Two, Gatsby provides a web pack and Babel config similar to Create React app, so we could start with a scaffolded project and extend as needed. And three, Gatsby supports MDX, so we could write component documentation using Markdown, import React components right into the file, and it just works even better. MDX compiles down into semantic HTML, which in turn gives the site improved accessibility. Better support for users that rely on assistive technology to access the docs, if a design system's promoting inclusivity in general, and really should, it follows that inclusive docs make sense.

As a bonus, Gatsby, we streamed our stuff from two repos to one and reduced the amount of CLI commands dramatically. The default setup for Gatsby is great. However, we needed to make some adjustments so Gatsby worked for our needs. In the gatsby-config file, we added Gatsby-plugin-post-css to support post-css. Gatsby-plugin-compile-es6 packages to support our design system package. Gatsby-plugin-mdx, so the site would recognize MDX files. Gatsby-remark-autolink headers to generate auto links for page headings for better screen reader and keyboard support. Gatsby-plugin-page-creator to create pages from the source pages folder. And Gatsby-plugin-filesystem so we could pull in our data file and point Gatsby to the folder where all our component MDX files lived. In the Gatsby node file, we added a GraphQL query to find the component MDX content. And it create page action to routes and pages for the component docs. In the Gatsby browser file, we added things we wanted to apply throughout the site, like our global CSS styles and the wrap route element component. The wrap root element component acts as a wrapper around the site's root element and imports the MDX provider.

3. Enhancing Component Documentation with MDX

Short description:

The MDX renderer was needed to wrap the contents of our component page template, ensuring proper rendering in the browser. React components can now be easily added to MDX files, allowing for seamless rendering. Custom components can be created for ordered lists, providing a nicely styled do's and don'ts list. MDX also enhances code block support, allowing for custom styling and different types of code blocks. By adding the React live prop, code blocks can be made editable and changes can be seen in real time.

This way, the entire site would recognize MDX content. We had to do one extra thing for our component docs page template though. Since our component MDX files were located outside of source directory, MDX renderer was needed to wrap the contents of our component page template. Otherwise, MDX files would render like this in the browser.

Now that our layout template used MDX renderer, our component MDX pages would render as we want in the browser. Now we could pop in React components next to code blocks in our MDX, and they would render, no problem. We could even wrap a buttoned component with a display box component and add a more cohesive look to the component code block pairing. If we wanted to add a props table to show which props can be used with a component and created a component that pulled in data to render as a data, a table of a props table component, pop that component into the docs MDX file and dots MDX file, I can speak today, passed in the name of the component to render, voila, the docs would show a props table.

For our component do's and don'ts, we used to have to write out an unordered list in the markdown file and the links and the list rendered like this. With MDX support, we instead created a custom component that renders on ordered lists. We could pass in a do's list and a don'ts list array into that component and boom, a nicely styled do's and don'ts list. Code blocks. Markdown has great code block support. MDX makes those even more powerful. So we were psyched to add this feature. You can override the styling of a code block in an MDX file with a custom code block or even display different types of code blocks. You can use Prism React Renderer in a custom code block component and import a theme with good color contrast like Sarah Drasner's night owl theme. Then you can wrap your code block and theme it. Import that code block component into your wrap root element along with the predecode block utility and override the default pre tag styling at the app level by passing it in as a component to the root wrap element. So now when you write a code block in MDX, instead of the baseline styling, the custom code block will render with syntax highlighting. Fun fact, you can pass in a prop to that code block and do really cool things if you use custom code blocks. For example, if you abstract this MDX into a dryer pattern in our custom code block component and pass the display box prop into that code block, if you add the display box prop to the code block in MDX, you'll get a code, you'll get a display box paired with a code block. Now, what about if you want your code block to be an editable code block? You can add a React live option to the component and show the component inside a display box pairing with an editable code block. So if you add the React live prop to your MDX code block, you'll get an editable code block and see your changes in real time. So if we write something like this, where we have three, three code blocks in MDX one with the React live prop, one with no prop just the name of the language and the third one with the display box prop passed in. This is what you will see. So over here is, I comped up a quick MDX file in my blog site to demo if you pass in, this one is the JSX with the React live prop passed in. This one is with just JSX passed in as the code. And this one is the passing in the display box prop to the JSX code block. What is great about the one with the React live prop is we are combining well the display box, fanciness and the block here, but this is now editable.

4. Enhancing Documentation with Editable Code Blocks

Short description:

By adding editable React Live support to code blocks, developers can easily play with component properties in the documentation. This provides a more interactive and intuitive way to understand how to use the component. It also allows learners to experiment and see how different inputs affect the component's behavior.

So I can do things with it. And if I know what props my component supports, I could make this button. If you see, look at there, it actually has error handling, but small button, wow. And I could also, I want, I know I support icons, so the icon I could use is the right arrow because I'm using React Font Awesome components under the hood. Look at that, I just added a icon to my button. But this, adding this type of editable block, editable React Live support to your code blocks is very powerful because your developers will be able to go into your component, into your documentation and play with the properties right there and understand how to use your component right away versus having to try, you know, look through all your props tables. This is another way for learners that need to type things to see how things break. So, editable block component, editable code blocks are amazing.

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 React.dev Story
A behind the scenes look at the design and development of the all-new React docs at react.dev. The new react.dev 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.