Scalable* Way of

Doing Open Source* for humans

About me

About me

@michaelklishi

n

About me

About me

clojurewerkz.or

g

About me

About me

recognised animated

gif connoisseur

About this talk

More open source producers

Exponentially more open

source consumers

Responsibility

ClojureWerkz

In 2011

• 4 projects

In 2011

• 4 projects

• 2 people

In 2011

• 4 projects

• 2 people

• Single digit external

users (tiny startups)

In 2011

• 4 projects

• 2 people

• Single digit external

users (tiny startups)

• Little documentation

In 2015

• Over 30 projects

In 2015

• Over 30 projects

• 5 people, ~70

contributors

In 2015

• Over 30 projects

• 5 people, ~70

contributors

• SMEs, Fortune 100,

governments, tiny

startups, academics

In 2015

• Over 30 projects

• 5 people, ~70

contributors

• SMEs, Fortune 100,

governments, tiny

startups, academics

• Well over 1000 hours

spent writing and

editing doc guides

Responsibility

responsibility |riˌspänsəˈbilətē|

noun ( pl. responsibilities )

the state or fact of having a duty to deal

with something or of having control over

someone

A responsible maintainer

makes sure the users

aren’t angry

Why can they be angry?

• Incorrect

expectations/assumpti

ons

• Incorrect

expectations/assumpti

ons

• Unexpected changes

• Unexpected changes

• Nobody to help

• Unexpected changes

• Nobody to help

• Too hard to contribute

• Unexpected changes

• Nobody to help

• Too hard to contribute

• Maintainer is an a-

hole

Solvable?

Have a helpful README

What does this thing do?

How mature is it?

How do I install it?

What runtimes and/or

versions are supported?

What license does it use?

Where can I get help?

Have a mailing list

Let community members

help you help your users

Helping others earns

their respect

Keep a change log

Keep a useful change log

No, git log is not a change log

Do you write brilliantly

detailed commit messages?

git log is often hard to interpret

for project outsiders

Provide details for humans

Developer vs. Ops

Post release announcements

Have a project blog

Have a Twitter account

Care about backwards

compatibility

Document well

“My favourite part about ClojureWerkz

is documentation…”

Documentation breeds trust

Make it easy to contribute

Explain the basics of

development process

Explain how to install & run

dependencies

travis-ci.org

Help beginners help you

Don’t be an a-hole

“It sounds too fucking hard”

Does anyone have the time

for that?

Standardise

Standardise

• README

Standardise

• README

• Change log

format

Standardise

• README

• Change log

format

• Announcement

format

Standardise

• README

• Change log

format

• Announcement

format

• Project layout

(Leiningen

templates)

Standardise

• README

• Change log

format

• Announcement

format

• Project layout

(Leiningen

templates)

• Same process

and practices

across the board

Automate

Automate• Clojure projects

typically have a highly

regular structure

Automate• Clojure projects

typically have a highly

regular structure

• Release process

Automate• Clojure projects

typically have a highly

regular structure

• Release process

• Documentation

deployment

Automate• Clojure projects

typically have a highly

regular structure

• Release process

• Documentation

deployment

• Some things (e.g.

announcements) are

still better done by

hand (our experience)

Engage contributors

Engage

contributors• Respond quickly

Engage

contributors• Respond quickly

• Be respectful

Engage

contributors• Respond quickly

• Be respectful

• Provide context

Engage

contributors• Respond quickly

• Be respectful

• Provide context

• Encourage them to

help

Engage

contributors• Respond quickly

• Be respectful

• Provide context

• Encourage them to

help

• Give them credits (in

the change log, on

Twitter, etc)

Engage

contributors• Respond quickly

• Be respectful

• Provide context

• Encourage them to

help

• Give them credits (in

the change log, on

Twitter, etc)

• Add frequent

contributors as

collaborators

Use data

Use data

• Common questions

Use data

• Common questions

• Bug reports

Use data

• Common questions

• Bug reports

• Your time

Use data

• Common questions

• Bug reports

• Your time

• Who contributes most

Writing

documentation

Writing

documentation• Don't put it off till

release time

Writing

documentation• Don't put it off till

release time

• Write guide structure

first

Writing

documentation• Don't put it off till

release time

• Write guide structure

first

• Ask others to edit

Writing

documentation• Don't put it off till

release time

• Write guide structure

first

• Ask others to edit

• A complete Getting

Started guide is better

than 4 unfinished ones

Writing

documentation• Don't put it off till

release time

• Write guide structure

first

• Ask others to edit

• A complete Getting

Started guide is better

than 4 unfinished ones

• Guides reduce amount

of time spent doing

support

Writing

documentation• Don't put it off till

release time

• Write guide structure

first

• Ask others to edit

• A complete Getting

Started guide is better

than 4 unfinished ones

• Guides reduce amount

of time spent doing

support

• Guides encourage

people to contribute by

giving them confidence

“But what if I’m no longer interested

in maintaining X?”

Pass it on

No matter what you do,

don’t release abandonware

”But who cares, it’s not my

problem what the users will do”

Fair enough

But it’s your reputation

Open source is one of the best

ways to market yourself

as an engineer

Thank you

@michaelklishi

nclojurewerkz.or

g