Live Editing React Components for Better Documentation

As stated in a previous post about documentation, "Your Docs And You", the best response to well made docs is simply, "I get it!"

When writing documentation, it's sometimes easy to forget that someone on the other end will actually be reading your docs. Writing docs can be as difficult as writing a book (albeit, most of the time much shorter). If the docs are too long and dull, you run the risk of the reader losing interest, but if they're too short and prioritize brevity over solid information, they won't end up being helpful.

When looking at React projects on GitHub, you can see that the most common approach to documentation is to add some descriptions, a couple of code examples, and one or more demos. With the addition of docs on the API of a library or project, this delivers a fairly complete picture to aspiring users.

While these resources are invaluable for learning how single parts of a React project work, it's tough to get a big picture overview of how it feels to use. People learn and become familiar with something tremendously faster when they can simply use and play around with it. So why can't we add a feature enabling this idea in our docs?

A playground full of components

To solve this problem, Formidable introduced component-playground. It allows you to render editable code side alongside of a demo, and updates the demoed React components in real time.

Using this project has allowed us to build docs that immediately give you feedback on how a project's components behave, what they look like, and most importantly what it feels like to use the library.

By enabling users to immediately use a library, we prevent users from becoming frustrated by unpractical, dull docs.

Spreading the live-editing love

The next step beyond adding live, editable demos to docs, was to add live, editable React code to every project that might need it. This idea subsequently led to the creation of a leaner alternative to component-playground.

Say hi to component-playground's little brother, react-live: a production-focused playground for live editing React components.

React Live is built to fulfill the additional requirements that arise when adding a live edit feature to a project.

1. It is built modularly, so it comes with separate components that are similar to the ones that make up component-playground. Namely an editor, a preview, an error view, and a provider.

2. In a production-focused web app that users load every day, it is important for React Live to load as quickly as possible. That’s why it's built using Bublé and Prism, bringing its size down to just 65kB gzipped. It's also server-side renderable!

3. It is easily and highly styleable, and thus easy to integrate into every possible environment that you might want to use it in.

These new improvements make it possible to use React Live creatively for new features, some of which we haven’t even thought of yet.

For example, want to make the homepage itself editable in your next docs? Consider it possible! styled-components docs, the first website using React Live in production, is doing just that.

We're excited to see what you might come up with! Ping us on Twitter to show us what you’ve created with React Live.