How to improve the DX of your readme with embeddable demos
Ian Jennings
Posted on September 14, 2022
While your readme might make sense to you, chances are you’ve probably left out some important information that other developers would appreciate. Just think about all the readmes you’ve followed. Have you ever had one where you wish the author provided better information such as:
- Shows commands, but not their output
- Only a documentation reference, but no examples of usage
- Broken or missing demos
- Need to clone and install just to run the demos
- Detailed contribution guidelines, but nothing about usage
These problems negatively impact the DX (developer experience) for devs who want to get started with your product. Every time developers get confused, encounter a bug, or have a question, it costs them time, and they’re more likely to give up using your tool.
Unsurprisingly, it’s hard to empathize with newbies who haven’t used your repository before. You already know how everything works, and it’s hard to guess what a newbie would need to know.
That’s why we made Replayable. Replayable helps developers upgrade their readmes, bug reports, and pull requests with video so other developers can understand the context behind their contributions.
Rather than jotting instructions down in text format, Replayable simply captures your screen as you work so you can easily attach video clips that contain an exact record of what actually happened.
Replayable captures all of the context, the running demos, the CLI output, usage, and how you – the creator – use the product. A demo is worth a thousand words, and Replayable transforms your everyday work into demos you can share with your audience.
Replayable vs Video Tutorials
Why video? While your code, examples, and prose may be enough to give developers an overview, videos capture your entire point of view. Rather than trying to explain your process manually (lossy), videos tell a complete story to your reader. In fact, 60% of developers report using videos to learn how to code.
Now if you’re not in that 60% you may be thinking, “I hate learning from videos!” Traditional videos for developers are long, boring, and unsearchable. Replayable allows you to create short clips to embed in readmes rather than long unbearable videos.
The unique thing about Replayable is that it makes adding video as easy as setting up your own project!
Rather than stopping what you’re doing, turning on your webcam, microphone, and trying to nail the perfect demo, Replayable keeps you in the flow by making it easy to add short clips along the way. Just hit the hotkey, trim, crop, and embed.
Not only that, but tutorials created with Replayable are easier to maintain. When they go out of date, all you need to do is update a single part rather than re-render the entire video clip.
Walkthrough
Get Replayable
Let’s get started! To start, you’ll need the Replayable desktop client.
Replayable runs in the background so you don’t need to start or stop recording while you work.
Instead, you’ll simply hit Create Clip or use the hotkey to capture whatever just happened on your screen. Replayable keeps a rolling buffer locally on your computer, which you’ll be able to review and edit before uploading.
Make a new Replayable project
Replayable projects are like folders. Every time you change repositories or local projects, you’ll probably want to make a new Replayable project as well.
Use the existing guide as a baseline
Now, it’s time to make a tutorial. Your tutorial will probably mix existing setup guides and some with your own spin. After all, a lot of development is implied. It’s our job to document every nook and cranny that a newbie might not infer.
This tutorial will work on improving the getting started guide for reveal.js, a JS framework for making presentations. We’re going to follow their install guide as a base:
## Full Setup <span class="text-gray-500 font-normal">- Recommended</span>{id="full-setup"}
Some reveal.js features, like external Markdown, require that presentations run from a local web server. The following instructions will set up such a server as well as all of the development tasks needed to make edits to the reveal.js source code.
1. Install [Node.js](https://nodejs.org/) (10.0.0 or later)
1. Clone the reveal.js repository
```
shell
$ git clone https://github.com/hakimel/reveal.js.git
```
1. Move to the reveal.js folder and install dependencies
```
shell
$ cd reveal.js && npm install
```
1. Serve the presentation and monitor source files for changes
```
shell
$ npm start
```
1. Open <http://localhost:8000> to view your presentation
Upgrade the tutorial with replays
Using the existing readme as a guide, follow the steps yourself in a clean environment . The first step is to install Node.js. As this is not unique to this repository and is likely well documented, it can be skipped.
Looking at the readme, the first step is to clone the repo. So do that on your machine. When you’re done, hit the Replayable hotkey to create a replay.
You can then crop the terminal and relevant browser page, then click the upload button. This will publish the replay to http://replayable.io and make it ready for sharing!
Watch Downloading and Installing Reveal.js on Replayable
Readmes on GitHub are created using the markdown format. To embed your replay within your readme, select Share and Markdown from the replay page. This will copy the markdown embed code to my clipboard. The markdown code includes a looping gif and a link to the replay.
You may also choose to turn the list into paragraphs to fit the embedded replays better. After every heading, paste the markdown code right after. Check out the final setup step below and the full result here.
# Getting Started with Reveal.js
Some reveal.js features, like external Markdown, require that presentations run from a local web server. The following instructions will set up such a server as well as all of the development tasks needed to make edits to the reveal.js source code.
## Download and Install
[](https://replayable.io/replay/630402cadf25a7006524c669/?share=AfkCnX717yYvNbX3juCDUQ)
Make sure you have [Node.js](https://nodejs.org/) (10.0.0 or later) installed. Then, clone the reveal.js repository:
```
git clone https://github.com/hakimel/reveal.js.git
```
Next, move to the reveal.js folder and install dependencies:
```
cd reveal.js
npm install
```
Then, do it again for the demo step!
Launch the app, view the presentation, and make changes. In the replay below, I wanted to understand how to modify my slides, so I launched VS Code and edited the first slide.
This is the kind of instruction where a video can be extremely helpful. While the text may make sense to you, a newbie might make errors when running npm start. They might not understand the relationship between the browser and the terminal in regards to “localhost,” and they probably don’t know what “monitor source files for changes” means.
Watch Setting up and running the Reveal.js Demo on Replayable
Not to mention, they probably can’t infer what will pop up once the demo runs. In fact, you probably don’t even know yet! So as you get the demo running for yourself, creating clips helps explain to others what the resulting output of these instructions is and provides context for how you got there.
## Run the Demo
[](https://replayable.io/replay/63040495973b2c0062e9239f/?share=tbbKqBecjPCoLBmb0QfCXw)
Serve the presentation and monitor source files for changes:
```
npm start
```
Then, open http://localhost:8000 to view your presentation!
Any changes you make to the source files will automatically be reflected in the presentation.
Publish the Tutorial
That’s it! You’re ready to publish. If you’re contributing to a repository, now you can open pull requests. Replayable embeds are supported everywhere, GitHub, Jira, WordPress, Dev.to, and more!
If you want to try Replayable out for yourself, join our beta and come hang out with us in Discord!
Posted on September 14, 2022
Join Our Newsletter. No Spam, Only the good stuff.
Sign up to receive the latest update from our blog.
Related