Andrey Sitnik, Evil Martians

How to Make a Popular Open Source Project

I am working at

15 Years Experience in Open Source

since 2004

5 Years Experience in Open Source Promoting

since 2013

Sharing Real Experience

Nano ID

Browserslist

PostCSS

Autoprefixer

3 M

50 M

80 M

30 M

Downloads per month

Chapter 1
Why you should create open source project?

Ты почему опенсорс не пишешь?

Часики-то тикают

Опенсорс надо писать пока молодой
Потом поздно будет

Что значит не хочешь?
Опенсорс все хотят

Дал Бог проект,

даст и PR

Halt and Catch Fire

“You must have OS project to find a job”

HR

“Success Formula”

Idea

GitHub

Popularity

Success

South Park, Go Fund Yourself episode

Open Source dream is a lie

Popular project ≠ many followers

Better ways to be popular

Articles

Talks

GitHub project ≠ good resume

1 month of work → few stars

vs

2 weeks → commit to Babel

Better ways to be popular

Create app

Fix docs in popular projects

Use beta version → fix bugs

The best reason: change the world

My reason for Autoprefixer: kill Compass

My reason for PostCSS: CSS tools diversity

Stylelint

Lost Grid

cssnano

RTLCSS

My reason for Size Limit: reduce JS lib size

Chapter 2
Success formula

False formula

Good idea Popular project

False

My open source projects

Nano ID

Browserslist

PostCSS

Autoprefixer

The real list of my projects

52 non-popular and only 4 popular

Fail case 1: Size Limit

Size Limit 0.1

Article about it

a week to write the article

bundlesize was released before my article

Size Limit 0.1

Article about it

Size Limit lost

Fail case 2: Autoprefixer

grid-template-rows: auto auto

Fail case 2: Autoprefixer

grid-template-rows: auto auto

The real success formula

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Idea is not important

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Idea

Useless project can’t be promoted

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Chapter 3
Base axioms

Axiom 1: success formula

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

How we think people choose frameworks

Rational choose across all options

How we think people choose frameworks

Rational choose across all options

False

Axiom 2: How people choose frameworks

Irrational choose across popular options

How we think people read docs/tweets

How we think people read docs/tweets

False

Axiom 3: How people read docs/tweets

Chapter 4
Preparations

Success formula has Popularity on both sides

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

My main mistake: only Russian announce

My main mistake: nobody to mention

Advice 1: Create English Twitter account

Success formula is based on luck

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Advice 2: Be ready to try many times

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

Chapter 5
README.md

README.md is your main entry point

How people read docs

What users need?

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

Advice 3: Start from the reason to read it

First block of PostCSS

PostCSS is a tool for transforming styles with JS plugins.

These plugins can lint your CSS, support variables and mixins, transpile future CSS syntax, inline images, and more.
 

PostCSS is used by industry leaders including Wikipedia, Twitter, Alibaba, and JetBrains. The Autoprefixer PostCSS plugin is one of the most popular CSS processors.

Clear description

How it could be useful

Why it is important

It’s OK to spend a week on the first block

First block of Autoprefixer

PostCSS plugin to parse CSS and add vendor prefixes to CSS rules using values from Can I Use.

It is recommended by Google and used in Twitter and Alibaba.

Clear description

Why it is important

First block of Nano ID

A tiny, secure, URL-friendly, unique string ID generator for JS.

  • Small. 141 bytes (minified and gzipped). No dependencies.
  • Safe. It uses cryptographically strong random APIs and tests distribution of symbols.
  • Fast. It’s 16% faster than UUID.
  • Compact. It uses a larger alphabet than UUID (A-Za-z0-9_-).

Clear description

Difference from analogs

What should be in first block

  1. Clear description
  2. How the product is useful for users
  3. The difference from other products

Bad example of first sentence

Svelte is cybernetically enhanced web apps

Svelte is JS framework with unique compiler

which generate smaller JS files

Not clear

How to make good description

You in the bar with friends.
”So, I created …”

And then cut it 2-4 times

What do you think people read

What people actually read

Progressive JPEG

Advice 4: More illustration or code example

Advice 5: More lists and bolds

Important parts are highlighted

Advice 6: Use real proofs

Size Limit to prove “small”

Show benchmarks to prove “fast”

Show code to prove “better API”

Advice 7: Step-by-step starting guide

Your users

Be very specific

Help with choice

Separated sections for specific use cases ❤️

Test your starting guide on new project

npm init

everything works

Chapter 6
Slow growing

Wrong way to promote the project

Post 1 tweet

Got 4 retweets

Grows by small iterations

Federico Panzano

Each iteration contains

  1. Action (feature, tweet, article, etc)
  2. Feedback
  3. Fixing the project according to feedback

Next iteration bigger than previous one

  1. Bigger action
  2. More feedback
  3. More things to fix

1st iteration: explain the idea to friends

And find the way to describe the project

2nd iteration: convince colleagues to try it

Fix issues, DX,
and install docs

3rd iteration: post announce to the Twitter

And find the best way to describe projects

And tweet again each big feature

Good tweet

Code example or screenshot

Project description

New feature which was added

4th iteration: reddit and hacker

And fix compatibility issues

5th iteration: write article on your language

habr.com

6th iteration: write English article

dev.to

smashingmagazine.com

css-tricks.com

7th iteration: send PRs

Use previous success in next iterations

Don’t step making interations

Don’t spam: be regular

every 2 weeks or every month

Why you need to several tweets?

Why you need many iterations?

Feedback will help to fix it

How people choose

Irrational choose across popular options

How long they will support the project?

How many resources project has behind?

Regular tweets answer to these questions

Irrational choose across popular options

How long they will support the project?

How many resources project has behind?

Chapter 7
Working with community

You did everything right

Explain benefits in docs

Good step-by-step intructions

Regular tweets, articles, talks

And got issues from users

The circle of guilt

Many issues without answer

Blaming yourself for being bad maintaner

Depression and lack of productivity

Even more issues without answer

You don’t need to write code

15 min in the morning to answer on new issues

It’s OK to ask wait

Just an answer could make them your fans

Do something to avoid issues in future

Add warning

Stopped issues about using PostCSS for Sass sources

Add note to docs

Ask issue authors to change docs

How to deal with negative feedback?

There is no ideal answer

My best way is to start asking questions

Sometimes, people just need to talk

They can become your fan

after a talk

Chapter 8
Resume

Success formula

Project popularity =
Your popularity
Promotion
Benefits for users
Luck

+

+

+

How people choose

Irrational choose across popular options

How people read

README.md is critical

  1. Clear description
  2. How the product is useful for users
  3. The difference from other products
  4. Easy step-by-step instruction

Regular tweets, articles, talks

Thanks

DM me your open source