Who has ever... ● Posted on the mailing list or forum ● Collaborated in IRC ● Answered a question on Stack Overflow ● Written a technical blog post ● Opened an issue on GitHub ● Attended a hack day event ● Submitted a pull request ● Published a bundle
There is no shortage of opportunity.
OSS projects need... Evangelism Documentation Support Development
How do we... Discover open-source projects? Elect to use them? Become motivated to contribute?
We do not have an infinite supply of Lukas Smiths.
Share Your Experience ● For current and prospective users ○ Blog posts ○ Case studies ● For project members ○ Answering RFC's ○ Weighing new features or changes ○ Highlighting what works and doesn't
Feedback Guides Decision Making* Praise → Reinforcement Criticism → Reevaluation *Except when it doesn't
Don't Omit Criticism Positive feedback loops are dangerous. The best criticism is constructive. Good decisions require objectivity.
Be an advocate, not a fanboy.
Growing the Community ● As individuals ○ Attend conferences ○ Host local meetups ○ Make friends! ● As companies ○ Sponsor the above
How do we... Get up and running? Learn how to use a project? Get acquainted with a new API?
We do not have an infinite supply of Ryan Weavers.
Myth: Rock stars only write code... ...and this guy writes the documentation.
Documentation comes in all forms. ● Code ● API docs ● Test cases ● README ● The Book™ ● Cookbooks and tutorials ● Starter apps and distributions
But most users need these: ● Code ● API docs ● Test cases ● README ● The Book™ ● Cookbooks and tutorials ● Starter apps and distributions
Ingredients for great documentation: Consistent writing style. Users make the best authors. Evolves as the code changes.
Wrong documentation is dangerous.
Writing proficiency is essential.
Before You Commit ● Follow conventions ○ Formatting ○ Structure ○ Writing style ● Test your changes ○ Content: grammar, spelling, links ○ Syntax: reStructuredText, Markdown, HTML ○ Build: Sphinx, Docbook
Users expect things to work. Some users ask questions. Good users file bug reports. Awesome users submit patches.
We do not have an infinite supply of Christophe Coevoets.
Support is... Often a thankless job. Necessary for growth. Never finished.
The Relentless Flow of Questions ● Why is the user asking this? ● Refer to existing content if possible ○ Previous discussions ○ Relevant documentation ● Good exchanges deserve visibility
Bug Reports ● Encourage users to report actual issues ○ Handle security vulnerabilities responsibly ● Triaging saves time ○ Identify duplicate and invalid reports ○ Cross-reference related or upstream issues ● Fill in the gaps ○ Collect background information ○ Create failing test cases ○ Document workarounds