September 18, 2018
Zhenchao Qi
The best techniques for sharing code snippets and screencasts that will help propel your open source projects to success.


Creating your own open source projects can be extremely rewarding, but it can be hard to break through the noise and get other developers to trust and use your software. You can gain a lot of ground by following common best practices like including solid documentation, adding unit tests, integrating with a CI/CD oriented towards open-source projects (like travis-ci or circle-ci), and enforcing consistent style conventions.
One of the most effective and easiest ways I’ve found to make open source projects really stand out from the crowd is adding quality screenshots or animated demos. Whenever I see this attention to detail, not only does it prove to me that the author cares about the project, but it’s the absolute fastest way to convey what the project actually does.
我实习的地方是一个赌场度假村聚集的城市,被人们称作全美第二大赌城的 Atlantic City,位于纽约南部的新泽西州,而我申请的工作地点就是Harrahs, 同时也是Atlantic City最出名的三大赌场之一。暑期有很多人慕名前来,是一个度假村一样的休闲娱乐城市。而我的工作是客房服务岗,既然是带薪实习,也就是工作,意味着一份责任。观察了近一周美国人的工作后,我深刻感受到每位美国员工身上强烈的责任感和使命感,所以我也为自己制定了目标——高标准地完成每天的工作任务。每天十六间客房的工作看似轻松,可对于初来乍到的我,更像是一份无法完成的任务。我耐心观察老员工的工作技巧,从床到浴室到地毯,有条不紊。当知道自己通过测试,并且明天就要开始上班的时候,感觉自己真的长大了!
  • Static code snippets (images)
  • Animated code demos (GIFs or animated SVGs)
  • Project screencasts (videos)

Static Code Snippets

在美国的每一天,我不是一个被工作束缚并祈求生活权利的人,而是一个为了追求更好生活而努力奋斗的好好先生。我爱生活,更爱在美国的生活。无论白天的工作再辛苦,下班后我总会把家收拾得干干净净,家里的角角落落都像是被管家刚清扫过一样。每周我都会去walmart采购蔬菜、水果、肉类以及其他生活必需品,做菜也成了爱好。在这里生活,我好像不再是国内普普通通的一名大二学生,而是一名热爱厨艺与健身,在Harrah’s Casino有正经工作的青年。我似乎受到了在国内没有的尊重,生活得更像一个社会人。

GitHub-Flavored Markdown Snippets

当然工作之余,我会和小伙伴结伴出游,一起做攻略,去费城,纽约,尼亚加拉大瀑布,在爱彼迎上抢房源,和uber司机畅聊中美文化,在奥莱里面疯狂shopping ,在chainsmoker 的沙滩音乐节上体验美式狂欢,这一切都发生在美国,在这个没有人和我说中文的地方。而我也把交流变成了蹦词加比划。三个月,英语看似强了不少,但我觉得真正强的是敢于开口的勇气。
const pMap = require('p-map') const got = require('got') const sites = [ getWebsiteFromUsername('sindresorhus'), //=> Promise 'ava.li', 'todomvc.com', 'github.com' ] const mapper = el => got.head(el).then(res => res.requestUrl) pMap(sites, mapper, { concurrency: 2 }) .then(result => { console.log(result) //=> ['http://sindresorhus.com/', 'http://ava.li/', 'http://todomvc.com/', 'http://github.com/'] })
Image Credit: Carbon
Image Credit: Carbon

Animated Code Demos

Including a high quality, inline demo that quickly demonstrates your project’s core use case is the single most important suggestion I have to give.
There are a ton of different ways to go about creating these types of demos, however, so I’d like to discuss what I’ve found to be the best approach here.
Asciinema is a free tool that lets you record and share your terminal sessions, the right way.
Asciinema provides a lightweight, purely text-based approach to terminal recording, which allows you to make lossless recordings that can then be shared directly or rendered to animated SVG, animated GIF, or video. It surprised me just how many popular open source projects on GitHub make use of Asciinema — I would highly recommend checking it out.
Example Asciinema screencast converted to a GIF (credit: create-react-library) Note that the quality of this embedded GIF is much lower than the animated SVG in the linked readme as discussed below.
Example Asciinema screencast converted to a GIF (credit: create-react-library) Note that the quality of this embedded GIF is much lower than the animated SVG in the linked readme as discussed below.

Animated SVG or GIFs?

We all know GIFs are a horribly inefficient, lossy format, but let’s dig a little deeper into this particular use case.
Compare the above embedded screencast gif to the animated SVG of the same screencast from the readme. It’s difficult to embed an inline comparison side-by-side, but the animated SVG is significantly sharper and smaller, coming in at 73kb vs 4.4MB for the lower quality GIF.
Why is this even a discussion then? Well, you can’t exactly include custom HTML in a Medium blog post, now can you? And for that matter, there are a lot of places where using custom animated SVGs won’t fly, and for the foreseeable future, GIFs will live on as a fallback for those use cases. But open source authors, please consider using animated SVG versus GIFs for your GitHub projects!
There are some very popular open source projects on GitHub that have started using more efficient animated SVGs for their demos, such as create-react-app, but in general, you’ll find GIFs to be much more common.
Here's a few examples of using the excellent svg-term-cli to generate our lossless animated SVG.
# generate animated SVG svg-term --cast 'fxdtpprue51QZkeViQurqPg8V' --out demo.svg --window --width=80 --height=24 --term=iterm2 --profile=Snazzy # generate single frame SVG at 20 seconds into the screencast svg-term --cast 'fxdtpprue51QZkeViQurqPg8V' --out screenshot.svg --window --width=80 --height=24 --term=iterm2 --profile=Snazzy --at 20000
It’s important to note that when discussing animated SVGs, we’re really talking about embedding an HTML snippet into GitHub-flavored markdown that links to an SVG file encoded with each frame as an SVG group and the animation defined via CSS keyframes (example SVG source).
<p align="center"> <img width="600" src="https://cdn.rawgit.com/transitive-bullshit/create-react-library/master/media/demo.svg"> </p>
Insert this HTML snippet into any GitHub-flavored markdown file to embed the linked animated SVG with optimal sharpness and low size overhead compared with a comparable GIF.
For reference, here is the screencast from create-react-library we’ve been using as an example in several different formats:

Capturing and Optimizing GIFs

Asciinema is great for terminal-based recording, but what if you want to record a UI component or website? Well, my first and foremost answer here is to always include a usable demo if possible alongside your project, especially if it’s a frontend web project. It’s really easy to get started with GitHub Page’s free hosting!
If you do want to include a GIF, I’d recommend using either GIPHY Capture or Kap to record your screen and output a GIF. Alternatively, if you have a video recorded from another source, I’d recommend using Gifski to convert the video to an as-optimized-as-possible GIF for ease of embedding.
<!-- html snippet customizing embedded gif --> <img src="https://cdn.rawgit.com/terkelg/prompts/master/media/number.gif" alt="example prompt" width="499" height="103" /> <!-- raw markdown can also be used to ambed a gif --> ![](https://cdn.rawgit.com/terkelg/prompts/master/media/number.gif)
Quality demo GIF embedded in readme using the snippet above. (image credit: prompts by terkelg)
Quality demo GIF embedded in readme using the snippet above. (image credit: prompts by terkelg)

Project Screencasts

If your project is becoming more involved or you’re launching your project to a wider audience, including walkthrough video(s) can really help with user onboarding and support.


My go-to screen recording software is ScreenFlow, which is not cheap at $129, but gives you a lot of powerful, quality tools for the price, including precise rectangular screen recording, video and audio track mixing, audio voiceovers, transition effects, and more. This type of screencast is quite a bit more complicated than the screenshots and terminal session recordings we were looking at earlier.


Developer UX is important for promoting and marketing your work, which can in turn lead to very real consequences, as getting noticed for your open source contributions is definitely one of the best ways to gain notoriety and land big job opportunities as a software engineer.
I hope some of the techniques I’ve covered help you to promote your open source projects. If you’ve found this article useful and end up creating a snazzy screenshot or animated demo, add a comment linking to your project and let me know!
And as always, don’t forget to spread the ❤️… in the form of beautiful coding demos, of course!

Follow me on twitter for more awesome stuff like this @transitive_bs