Designing Useful Contributing Guides (OSSAT Talk)

•

Apr. 25, 2016

• •

@nayafia
Designing Useful
Contributing Guides
@nayafia for OSSAT

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

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

Next SlideShares

Upcoming SlideShare

Rebuilding the cathedral

Rebuilding the cathedral

Loading in …3

×

Designing Useful Contributing Guides (OSSAT Talk)

Apr. 25, 2016

• •

Download to read offline

What makes a good open source contributing guide? Highlights and best practices from research. From an Open Source Show and Tell talk in San Francisco, April 22 2016.

Template referenced in the talk can be found here: https://github.com/nayafia/contributing-template

FOOTNOTES
Slides 3 and 4: Based on GitHub Search conducted Apr 18 2016. Thanks Brandon Keepers (@bkeepers) for helping with this!
Slides 5 and 6: https://peerj.com/preprints/1233.pdf
Slides 7 and 8: Current as of Apr 18 2016
Slide 20: http://read-the-docs.readthedocs.org/en/latest/contribute.html
Slide 21: https://github.com/plataformatec/devise/wiki/Contributing
Slide 22: https://docs.djangoproject.com/en/dev/internals/contributing/new-contributors/#guidelines
Slide 23: https://github.com/angular/material/blob/master/CONTRIBUTING.md#-git-commit-guidelines
Slide 24: https://github.com/celery/celery/blob/master/CONTRIBUTING.rst#security

What makes a good open source contributing guide? Highlights and best practices from research. From an Open Source Show and Tell talk in San Francisco, April 22 2016.

Template referenced in the talk can be found here: https://github.com/nayafia/contributing-template

FOOTNOTES
Slides 3 and 4: Based on GitHub Search conducted Apr 18 2016. Thanks Brandon Keepers (@bkeepers) for helping with this!
Slides 5 and 6: https://peerj.com/preprints/1233.pdf
Slides 7 and 8: Current as of Apr 18 2016
Slide 20: http://read-the-docs.readthedocs.org/en/latest/contribute.html
Slide 21: https://github.com/plataformatec/devise/wiki/Contributing
Slide 22: https://docs.djangoproject.com/en/dev/internals/contributing/new-contributors/#guidelines
Slide 23: https://github.com/angular/material/blob/master/CONTRIBUTING.md#-git-commit-guidelines
Slide 24: https://github.com/celery/celery/blob/master/CONTRIBUTING.rst#security

More Related Content

Tubes: A Journey to the Center of the Internet Andrew Blum

Emergence: The Connected Lives of Ants, Brains, Cities, and Software Steven Johnson

The Impulse Economy: Understanding Mobile Shoppers and What Makes Them Buy Gary Schwartz

An Army of Davids: How Markets and Technology Empower Ordinary People to Beat Big Media, Big Government, and Other Goliaths Glenn Reynolds

World Wide Mind: The Coming Integration of Humanity, Machines, and the Internet Michael Chorost

In the Plex: How Google Thinks, Works, and Shapes Our Lives Steven Levy

Hamlet's BlackBerry: A Practical Philosophy for Building a Good Life in the Digital Age William Powers

Talking Back to Facebook: The Common Sense Guide to Raising Kids in the Digital Age James P. Steyer

The Thank You Economy Gary Vaynerchuk

Socialnomics: How Social Media Transforms the Way We Live and Do Business Erik Qualman

The Nature of the Future: Dispatches from the Socialstructed World Marina Gorbis

Public Parts: How Sharing in the Digital Age Improves the Way We Work and Live Jeff Jarvis

Blog Schmog: The Truth About What Blogs Can (and Can't) Do for Your Business Robert W. Bly

The End of Business As Usual: Rewire the Way You Work to Succeed in the Consumer Revolution Brian Solis

101 Awesome Builds: Minecraft® Secrets from the World's Greatest Crafters Triumph Books

How to Be Invisible: Protect Your Home, Your Children, Your Assets, and Your Life J. J. Luna

Cognitive Surplus: Creativity and Generosity in a Connected Age Clay Shirky

The New New Thing: A Silicon Valley Story Michael Lewis

The History of the Future: Oculus, Facebook, and the Revolution That Swept Virtual Reality Blake J. Harris

Everybody Lies: Big Data, New Data, and What the Internet Can Tell Us About Who We Really Are Seth Stephens-Davidowitz

Ten Arguments for Deleting Your Social Media Accounts Right Now Jaron Lanier

The Social Life of Information: Updated, with a New Preface-Revised John Seely Brown

An Introduction to Information Theory: Symbols, Signals and Noise John R. Pierce

Who Owns the Future? Jaron Lanier

The Dark Net: Inside the Digital Underworld Jamie Bartlett

Alone Together: Why We Expect More from Technology and Less from Each Other Sherry Turkle

The Death of Expertise: The Campaign Against Established Knowledge and Why it Matters Tom Nichols

Algorithms to Live By: The Computer Science of Human Decisions Brian Christian

New Dark Age: Technology and the End of the Future James Bridle

The Emperor's New Mind: Concerning Computers, Minds, and the Laws of Physics Roger Penrose

Blockchain Revolution: How the Technology Behind Bitcoin Is Changing Money, Business, and the World Don Tapscott

Data and Goliath: The Hidden Battles to Capture Your Data and Control Your World Bruce Schneier

Designing Useful Contributing Guides (OSSAT Talk)

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