1.
Scalable* Way of
Doing Open Source
* for humans

2.
About me

3.
About me
@michaelklishi
n

4.
About me

5.
About me
clojurewerkz.or
g

6.
About me

7.
About me
recognised animated
gif connoisseur

8.
About this talk

9.
More open source producers

10.
Exponentially more open
source consumers

11.
Responsibility

12.
ClojureWerkz

13.
In 2011
• 4 projects

14.
In 2011
• 4 projects
• 2 people

15.
In 2011
• 4 projects
• 2 people
• Single digit external
users (tiny startups)

16.
In 2011
• 4 projects
• 2 people
• Single digit external
users (tiny startups)
• Little documentation

17.
In 2015
• Over 30 projects

18.
In 2015
• Over 30 projects
• 5 people, ~70
contributors

19.
In 2015
• Over 30 projects
• 5 people, ~70
contributors
• SMEs, Fortune 100,
governments, tiny
startups, academics

20.
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

21.
Responsibility

22.
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

23.
A responsible maintainer
makes sure the users
aren’t angry

24.
Why can they be angry?

25.
• Incorrect
expectations/assumpti
ons

26.
• Incorrect
expectations/assumpti
ons
• Unexpected changes

27.
• Unexpected changes
• Nobody to help

28.
• Unexpected changes
• Nobody to help
• Too hard to contribute

29.
• Unexpected changes
• Nobody to help
• Too hard to contribute
• Maintainer is an a-
hole

30.
Solvable?

31.
Have a helpful README

32.
What does this thing do?

33.
How mature is it?

34.
How do I install it?

35.
What runtimes and/or
versions are supported?

36.
What license does it use?

37.
Where can I get help?

38.
Have a mailing list

39.
Let community members
help you help your users

40.
Helping others earns
their respect

41.
Keep a change log

42.
Keep a useful change log

43.
No, git log is not a change log

44.
Do you write brilliantly
detailed commit messages?

45.
git log is often hard to interpret
for project outsiders

46.
Provide details for humans

47.
Developer vs. Ops

48.
Post release announcements

49.
Have a project blog

50.
Have a Twitter account

51.
Care about backwards
compatibility

52.
Document well

53.
My favourite part about ClojureWerkz
is documentation…”

54.
Documentation breeds trust

55.
Make it easy to contribute

56.
Explain the basics of
development process

57.
Explain how to install & run
dependencies

58.
travis-ci.org

59.
Help beginners help you

60.
Don’t be an a-hole

61.
“It sounds too fucking hard”

62.
Does anyone have the time
for that?

63.
Standardise

64.
Standardise
• README

65.
Standardise
• README
• Change log
format

66.
Standardise
• README
• Change log
format
• Announcement
format

67.
Standardise
• README
• Change log
format
• Announcement
format
• Project layout
(Leiningen
templates)

68.
Standardise
• README
• Change log
format
• Announcement
format
• Project layout
(Leiningen
templates)
• Same process
and practices
across the board

69.
Automate

70.
Automate
• Clojure projects
typically have a highly
regular structure

71.
Automate
• Clojure projects
typically have a highly
regular structure
• Release process

72.
Automate
• Clojure projects
typically have a highly
regular structure
• Release process
• Documentation
deployment

73.
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)

74.
Engage contributors

75.
Engage
contributors• Respond quickly

76.
Engage
contributors• Respond quickly
• Be respectful

77.
Engage
contributors• Respond quickly
• Be respectful
• Provide context

78.
Engage
contributors• Respond quickly
• Be respectful
• Provide context
• Encourage them to
help

79.
Engage
contributors• Respond quickly
• Be respectful
• Provide context
• Encourage them to
help
• Give them credits (in
the change log, on
Twitter, etc)

80.
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

81.
Use data

82.
Use data
• Common questions

83.
Use data
• Common questions
• Bug reports

84.
Use data
• Common questions
• Bug reports
• Your time

85.
Use data
• Common questions
• Bug reports
• Your time
• Who contributes most

86.
Writing
documentation

87.
Writing
documentation
• Don't put it off till
release time

88.
Writing
documentation
• Don't put it off till
release time
• Write guide structure
first

89.
Writing
documentation
• Don't put it off till
release time
• Write guide structure
first
• Ask others to edit

90.
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

91.
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

92.
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

93.
“But what if I’m no longer interested
in maintaining X?”

94.
Pass it on

95.
No matter what you do,
don’t release abandonware

96.
”But who cares, it’s not my
problem what the users will do”

97.
Fair enough

98.
But it’s your reputation

99.
Open source is one of the best
ways to market yourself
as an engineer

100.
Thank you

101.
@michaelklishi
nclojurewerkz.or
g