Live Editing React Components for Better Documentation
31 May 2017
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
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 .
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.
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!
- 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.