If you want to experiment with UI component libraries like Clarity, you must typically first download their code, setup a development environment and then copy and paste their examples into that code to try them out. Even then, most examples are not full-featured, so you can only get a rough sense of how you might be able to use them yourself.
What if you could not only see the code that runs any specific example without having to download it first, but also edit that code on the fly and see what happens as a result of your changes? That was the inspiration behind a new open source project my team has put together that we’re calling Live Docs.
I work with VMware Cloud Director, where I am one of two tech leads on our UI team. The Live Docs project began when we started building common UI components for ourselves. We were looking to help anyone writing plugins for our application both be more productive and more easily match the user experience offered by the overall application. In the same spirit, we wanted the documentation we created to empower our users to learn as quickly as possible. So we decided to offer examples of how to use a component, including the code that was used to generate it, within a live environment where developers could start editing it.
We quickly realized that what we were building would be useful beyond Cloud Director plugin developers. A number of existing UI libraries, such as Material UI, offer live, editable components, but none of them are reusable or have been made available to the open source community. So we pulled Live Docs out of Cloud Director and made it its own open source project.
Live Docs has three main features:
- You can display the true source code for examples
- You can display its documentation, including inputs and outputs for a component
- You can run your example in StackBlitz for faster learning
By dynamically creating online environments based on your source code, Live Docs allows you to keep your example components in your source code instead of maintaining a list of examples in online environments.
To try Live Docs, just download and then run our code scanner during your build. That scours through your code to retrieve the information required to instantiate your examples and display their documentation. By wrapping your example component with our example viewer component, Live Docs renders your example and adds a Source Code Viewer, API information and an “Edit in StackBlitz” button around it.
In addition to an example viewer, we created several components that can be sprinkled into your existing examples application if you want it to fit within an existing layout. Or you can use a larger component that renders all your examples in a predefined layout.
For a more detailed description of our process and how Live Docs works, check out the paper we wrote for VMware’s R&D Innovation Offsite (RADIO) conference. It also reports on a test we ran to measure Live Docs’ impact on productivity. We took two groups of developers with little UI experience and asked one to finish a simple task using Clarity’s standard documentation and the other to use a version with Live Docs enabled. We found that the group using the generated overviews and live examples completed their tasks three times faster than the standard documentation group.
While we initially built Live Docs to work with Clarity and several other internal libraries that we use, it can be used with any Angular library component. We’re now looking for help in extending it to support React, Vue.js, and plain JavaScript components.
It’s worth noting that Storybook, the popular tool for displaying UI library examples, does offer an add-on for live, editable examples for React and plans on supporting other frameworks eventually, but isn’t there yet. Storybook is also a framework, which means that you need to modify the way you write your examples to use it. In contrast, think of Live Docs as a tool in your tool kit that you can apply within the environment that you’re already using.
If you are interested in helping us in developing Live Docs further, we’d love to hear from you. Just head over to our GitHub page and get in touch.
Stay tuned to the Open Source Blog and follow us on Twitter (@vmwopensource) for additional resources and insights.
