1.
@nayafia
Designing Useful
Contributing Guides
@nayafia for OSSAT

2.
@nayafia
Contributing guides tell
people how to contribute
to your project

3.
@nayafia
GitHub has
recognized
CONTRIBUTING.md
as a standard since
2012

4.
@nayafia
But only 1.7M repos
on GitHub have
CONTRIBUTING.md
or .rst
(roughly 5-11% out of 35M or ~17M repos, depending how you count it)

5.
@nayafia
Referencing this
study from last
year...

6.
@nayafia
alexreisner/geocoder, celery/celery,
gruntjs/grunt, mbostock/d3,
sass/sass, ansible/ansible,
cucumber/cucumber, clojure/clojure,
plataformatec/devise, haml/haml,
bundler/bundler, jekyll/jekyll,
jquery/jquery, django/django,
android/platform_frameworks_base,
homebrew/homebrew, etcetcetc

7.
@nayafia
Half of projects
listed with a Truck
Factor of 1 don’t
have
CONTRIBUTING.md

8.
@nayafia
A third of projects
listed with Truck
Factor of 2 don’t
have
CONTRIBUTING.md

9.
@nayafia
We don’t want you
to get hit by a truck,
but if you did...

10.
@nayafia
...how would your
project live on??

11.
@nayafia
Why should you
care about
contributing guides?

12.
@nayafia
Contributing guides
help clarify your
commitment

13.
@nayafia
Contributing guides
help your project
grow

14.
@nayafia
Contributing guides
mean you have to do
less work

15.
@nayafia
What do good
contributing guides
look like?

16.
@nayafia
Looked at 40
projects: ½ on small
side, ¼ medium, ¼
large**
** this is totally handwavy gutfeel stuff based on what I vaguely know
about who’s contributing to and using these projects. plz forgive

17.
@nayafia
Good guides cover
basically the same
things, regardless of
size

18.
@nayafia
I’ll spare you the
boring stuff. Go here:
https://github.
com/nayafia/contributing-
template

19.
@nayafia
But here are some
highlights:

20.
@nayafia
Write a friendly
introduction

21.
@nayafia
Ask for the
contributions you want
Tell them what you are or aren’t looking for, ask for help on known issues, etc.

22.
@nayafia
Create a “Your First
Contribution” section

23.
@nayafia
Use templates and
label conventions
Standardized stuff makes your life easier.

24.
@nayafia
Explain security
disclosures
At bare minimum, let them know that if they find a security issue, they
should contact you privately, and tell them how to reach you.

25.
@nayafia
Questions?
https://github.
com/nayafia/contributing-
template