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

11. More open source producers

12. Exponentially more open
source consumers

13. Responsibility

14. ClojureWerkz

15. In 2011
• 4 projects

16. In 2011
• 4 projects
• 2 people

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

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

19. In 2015
• Over 30 projects

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

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

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

24. Responsibility

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

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

28. Why can they be angry?

29. • Incorrect
expectations/assumpti
ons

30. • Incorrect
expectations/assumpti
ons
• Unexpected changes

31. • Unexpected changes
• Nobody to help

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

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

34. Solvable?

35. Have a helpful README

37. What does this thing do?

38. How mature is it?

39. How do I install it?

40. What runtimes and/or
versions are supported?

41. What license does it use?

42. Where can I get help?

43. Have a mailing list

44. Let community members
help you help your users

45. Helping others earns
their respect

46. Keep a change log

47. Keep a useful change log

48. No, git log is not a change log

50. Do you write brilliantly
detailed commit messages?

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

52. Provide details for humans

53. Developer vs. Ops

54. Post release announcements

55. Have a project blog

56. Have a Twitter account

57. Care about backwards
compatibility

59. Document well

61. My favourite part about ClojureWerkz
is documentation…”

62. Documentation breeds trust

64. Make it easy to contribute

65. Explain the basics of
development process

66. Explain how to install & run
dependencies

67. travis-ci.org

69. Help beginners help you

74. Don’t be an a-hole

76. “It sounds too fucking hard”

77. Does anyone have the time
for that?

78. Standardise

80. Standardise
• README

81. Standardise
• README
• Change log
format

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

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

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

85. Automate

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

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

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

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

90. Engage contributors

91. Engage
contributors• Respond quickly

92. Engage
contributors• Respond quickly
• Be respectful

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

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

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

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

97. Use data

98. Use data
• Common questions

99. Use data
• Common questions
• Bug reports

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

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

102. Writing
documentation

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

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

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

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

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

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

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

111. Pass it on

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

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

114. Fair enough

115. But it’s your reputation

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

118. Thank you

119. @michaelklishi
nclojurewerkz.or
g