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.
Animation Credit: CSS-only coding animation by Chris Dermody
A picture is worth a thousand words. — Cliche saying that’s totes relevant
Including quality screenshots and demos is becoming an increasingly important part of what I’d call Developer UX, that is the flow a prospective developer takes from considering adding your project as a dependency all the way through successful integration and future maintenance.
Towards that end, we’ll be looking at three common use cases for improving the developer UX of your open source projects with media:
Sharing small bits of static code is definitely the most common and important use case on this list. Every open source project’s readme should include some easily parseable example usage snippet, so let’s start there.
At the easiest end of the spectrum, GitHub allows syntax highlighting in markdown code snippets. Hopefully, this style of embedding is familiar to you, and if not, I would definitely recommend starting here.
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/>']
})
The code snippet above also provides an example of an extremely popular way of sharing static code snippets via GitHub Gists, which have the following advantages: