Open source pairing workshop documentation party

[shamus]

Hi @aneyzberg! Hi @holyoke!

@ultrasaurus suggested we get together and write up what we've learned about running the open source pairing workshops we've been doing with 18F. I think the idea is that we would add a section to the bridge foundry website about these events.

Would you like to help? Is there a time next week that is good to meet up? 11/3 - 11/5 are particularly good for me.

If it would be helpful I'm happy to take a stab at a first draft beforehand. I currently have some extra time at work.

[aneyzberg]

@shamus That sounds great! I would love to help with that! 11/4 or 11/5 would work well for me.

[JasonEb]

11/4 would be a good day for me, i'll be working from the city.

Is there any particular l feedback to address?

[shamus]

Ok, lets plan on 11/4. We can either do something collaborative / online or hangout in person. I'm more of an in person kind of guy if that sways anybody. :)

@holyoke I don't think there's any particular feedback... I think the idea is to write up what we've learned so far so other people could benefit / organize their own. I'm not sure where what we write should live though. I had said the bridge foundry website, but that doesn't really like like the right place.

We should make a list of things we want to produce.

• participant experience (facilitating somebody's first PR, etc)
• organization experience (identifying work to be done, figuring out how to organize it, managing PRs)

I'm sure there's tons more

[aneyzberg]

Great. I can do in person if that works for everybody :) And Is there any kind of wiki similar to the RailsBridge wiki where we might be able to put this? I will take a look. Also a list is a good idea. Will think of things to add to it.

[shamus]

Checking in:

• Is this Wednesday still good?
• In my head we're meeting here at C5 but we haven't discussed a location at all. What is a good location for everybody?

[aneyzberg]

C5 works for me if that works for everyone else :)

[ultrasaurus]

Wed works for me at C5. What time?

[aneyzberg]

Im available around 6 or after.

[shamus]

Thats great, anytime after 5 works for me. Here's my number, you might have to call me to get in: 415.430.5387

[aneyzberg]

Sounds good. I will try and be there around 5:45

[JasonEb]

Same, I'll be there by 6

[JasonEb]

Hi everybody, here's a link to the notes I took of last night. Great
meeting!

https://docs.google.com/document/d/1ZLGZfPmEvAmslmpjVjVUMR8PjpO9rSCjmffD5M48uvQ/edit?usp=sharing

On Wed, Nov 4, 2015 at 1:52 PM, Anna Neyzberg notifications@github.com
wrote:

Sounds good. I will try and be there around 5:45

—
Reply to this email directly or view it on GitHub
#1 (comment)
.

[shamus]

Did we agree on meeting again? I cannot remember!

[aneyzberg]

I thought we did. But i can't remember for when :(

[shamus]

@aneyzberg would you mind emailing me? I'd like to ask you a question. jeremy@carbonfive.com

[shamus]

Hi everybody. I know we talked about meeting tonight, but I don't see any activity on the issue. Dunno if plans were made or not. BUT, I wanted to practice a technique I learned for organizing my writing so I went ahead and started putting together an outline that covers a lot of what we talked about.

Specifically I wanted to practice the techniques in The Minto Pyramid Principle. The basic premise is that people understand information best when its presented top down. She suggests setting up your content by establishing a Situation (a non-controversial set of facts describing why we're here), a Complication (a situation or a change that has caused a problem with the situation), a Question (what should we do about it), and an Answer (a set of steps describing how to solve the problem).

What follows is basically an outline that follows the Situation/Complication/Question/Answer format. I haven't gone so far as to start writing paragraphs or focusing on tone. But I hope this provides a good organization of what we've talked about so far.

Situation

• There are developers of all skill level who are interested in participating in open source software projects.
• There are many open source projects looking for help

Complication

• It can feel daunting to get involved in an open source project. Where to start?
  • How to begin understanding the codebase? Where to look first?
  • What is a good first contribution? A feature? Documentation?
  • What is the right way to submit a contribution
• There are also a lot of collaborative processes that developers may not realize are at work in open source
  • What place do PRs have in the contribution process
  • How to solicit feedback on your work
  • How to respond to feedback on your work

Question

How can we help make it easier to get involved in open source software.

Answer

Provide workshops, built around real world projects, that create a welcoming environment for developers to learn about the process of open source development. The following steps outline what we believe made the workshops with 18F and Open Data Maker successful.

Find an inspiring project

• An interesting / motivating project will create a sense of excitement at your workshop. Does the project have an altruisitic goal? Does it provide value to the community?
• A project with a clearly defined goal / upcoming milestone will help focus the participants at your workshop.
• A project which has the opportunity for people at all skill levels to contribute will make it easier to help anybody who comes to the workshop find a way to contribute
• A project with an easily visualize-able end state. Whether that is visual design of a set of screens, or a clearly understandable use case for a library.

Maintainer presence

• Somebody who can provide context for the project and its objectives
• Somebody who can articulate the upcoming milestone
• Somebody who can organize a backlog of work for the workshop
• Somebody who can facilitate getting started with the project
• Somebody who can answer questions about the features being worked on

Leverage your community

• Figure out who your community is. Is it centered around a language? Is it centered around an activity?
• There are members of your community who have open source experience.
• Invite members of your community with varying experience levels. This is an easy way to show people new to open source that its easy to get involved.
• It can also be inspiring to have more experienced contributors around, they can provide context, perspective, and tell stories about how they got involved.
• People are generally excited to show other's what they know. To help other's learn how to do what they do. Utilize this.

Provide a comfortable learning environment

• Identifying features and bugs that cover a variety of experience levels means both new and experienced developers a like can find a way to contribute
• Try to maintain close to a 1:1 ratio of people who have contributed to open source before and people who have not. Pair people who have contributed before with new contributors.
• If possible, use the new contributor's laptop so they are the one set up with the project
• If possible, use the new contributor's gitthub account. Have them fork the repo and make the PR. Not only do they learn about the process of forking and PRs but they also get the satisfaction of seeing work they did merged into the project's main code base.

Make it easy for everybody

• Keep the workshop casual, an evening after work
• A project maintainer, outside of identifying features to work on, shouldn't need to do too much prep
• Make it easy for people to submit partial work. A WIP PR is better than no PR. This way, the new contributor can get the experience they're after without needing to commit to finishing a bigger chunk of work.
• WIP PRs can be picked up by other people in later workshops, reducing the amount of work you need to do as a project maintainer.
• If you can schedule workshops every few weeks, make it easy for people to return to work if they're interested in completing a feature they picked up.

[aneyzberg]

This is super helpful. I have started writing out my section, but am not quite done with it yet. I think we meant to meet, but did not confirm. should we find a time to meet after the holiday?

[shamus]

Oh good! What do you think about fitting our sections into this format? @aneyzberg you're working on the "Why" which basically corresponds to the situation and complication sections. I'm working the the "What" which I think is the top of the answer section. And @holyoke is working on the how which are the four sections below answer.

We'd replace the headings "Situation", "Complication", "Question", and "Answer" for sure.

Also, @ultrasaurus I'd like to use some of this for a blog post here at Carbon Five. I'd love to present it as an article co-written by this group. I'd be happy to act as ghost writer.

[aneyzberg]

@shamus I think it would fit well into that formatting, and I love the idea of a blog post to share the info.

[ultrasaurus]

@shamus this is a great start!

I'd like to add something to "situation" that gets at the teaching/learning aspect that I was thinking about when we started the open source pairing workshops...

Situation

• There are a lot of developers who are new to coding or stuck using outdated languages and platforms in their day job
• Open source is a great way to get experience in a modern tech stack and demonstrate skills
• There are many open source projects looking for help
• There are developers of all skill level who are interested in participating in open source software projects.

What do you think? @aneyzberg @holyoke @shamus

[shamus]

Oh hey! It's been awhile. Sorry, the new year has been super busy.

I'd love to finish this up. @ultrasaurus I think those additions to the situation make sense.

Should we schedule a hangout or something to put some momentum into this and finish it?

[ultrasaurus]

yes! let's plan a hangout @shamus @aneyzberg @holyoke -- I don't have any plans for the long weekend, or some evening next week (except Tues)

[aneyzberg]

@ultrasaurus sorry for the delay in getting back to you on this. That sounds great. I could do next week except for Tuesday as well.

[ultrasaurus]

I proposed a hangout via Google calendar on Thursday evening at 7p -- invited @shamus @aneyzberg @holyoke . I am flexible about start time or day, but it's helpful to have on my calendar!

[JasonEb]

I'm stoked about this! Thursday is kind of rough for me...if we can consider Friday or the weekend, I'm more available, but if Thursday works for everybody, I'm more than happy to join via chat during the commute.

It'd be nice nonetheless, to address and apply some momentum on it. I've been reading into BridgeTroll's code recently, I think it'd be cool to see what everybody else is thinking about open source workshops.

[ultrasaurus]

Since @aneyzberg said "any day except Tues" and I'm available too... I've moved the calendar event to Friday!

[ultrasaurus]

@aneyzberg and I met and brainstormed a bit on where this should go and riffed a little on the content that @shamus had put in a comment above. Notes are at bottom of previous meeting notes.

Feel free to add comments/suggestions/edits... or meet with us on Monday evening @7:30. I sent a calendar invite.

[shamus]

Sorry to miss last night, I'll be there Monday though.

[ultrasaurus]

We think we have a draft that is good enough to publish as a first release. Please read and comment here: https://docs.google.com/document/d/1ZLGZfPmEvAmslmpjVjVUMR8PjpO9rSCjmffD5M48uvQ/edit#heading=h.n6060zps2x19

@aneyzberg will turn into markdown as a PR on bridgefoundry.org website at the end of the week

[aneyzberg]

Build Community With Open Source Pairing Workshops

Volunteers and students often leave a Bridge Workshop inspired and excited by the experience. Students may attend more workshops, but find they want real-world experience. Volunteers find they want the opportunity to reconnect with the same people.

Open source offers real-world, learning opportunities

• There are developers of all skill level who are interested in participating in open source software projects.
• There are many open source projects looking for help

Why isn’t it already happening?

• It can feel daunting to get involved in an open source project. Where to start?
  • How to begin understanding the codebase? Where to look first?
  • What is a good first contribution? A feature? Documentation?
  • What is the right way to submit a contribution
• There are also a lot of collaborative processes that developers may not realize are at work in open source
  • What place do PRs have in the contribution process
  • How to solicit feedback on your work

How to make it happen!

Provide workshops, built around real world projects, that create a welcoming environment for developers to build their skills by contributing to open source.

The following steps outline what we believe made the workshops with 18F and Open Data Maker successful.

Find an inspiring project

• An interesting / motivating project will create a sense of excitement at your workshop. Does the project have an altruistic goal? Does it provide value to the community?
• A project with a clearly defined goal / upcoming milestone will help focus the participants at your workshop.
• A project which has the opportunity for people at all skill levels to contribute will make it easier to help anybody who comes to the workshop find a way to contribute.
• A project with an easily visualize-able end state. Whether that is visual design of a set of screens, or a clearly understandable use case for a library.

Maintainer presence

• Somebody who can provide context for the project and its objectives
• Somebody who can articulate the upcoming milestone
• Somebody who can organize a backlog of work for the workshop
• Somebody who can facilitate getting started with the project
• Somebody who can answer questions about the features being worked on

Leverage your community

• Figure out who your community is. Is it centered around a language? Is it centered around an activity?
• There are members of your community who have open source experience.
• Invite members of your community with varying experience levels. This is an easy way to show people new to open source that it’s easy to get involved.
• It can also be inspiring to have more experienced contributors around, they can provide context, perspective, and tell stories about how they got involved.
• People are generally excited to show others what they know. To help others learn how to do what they do. Communicate how valuable this is — for the students and for the project.

Provide a comfortable learning environment

• Identifying features and bugs that cover a variety of experience levels means both new and experienced developers alike can find a way to contribute.
• Try to maintain close to a 1:1 ratio of people who have contributed to open source before and people who have not. Pair people who have contributed before with new contributors.
• If possible, use the new contributor's laptop so they are the one set up with the project.
• If possible, use the new contributor's github account. Have them fork the repo and make the PR. Not only do they learn about the process of forking and PRs but they also get the satisfaction of seeing work they did merged into the project's main code base.

Make it easy for everybody

• Keep the workshop casual, an evening after work
• A project maintainer, outside of identifying features to work on, shouldn't need to do too much prep
• Make it easy for people to submit partial work. A WIP PR is better than no PR. This way, the new contributor can get the experience they're after without needing to commit to finishing a bigger chunk of work.
• WIP PRs can be picked up by other people in later workshops, reducing the amount of work you need to do as a project maintainer.
• If you can schedule workshops every few weeks, make it easy for people to return to work if they're interested in completing a feature they picked up.

[aneyzberg]

@ultrasaurus @shamus @holyoke Here are the notes from our last meeting in Markdown. Does this look good to everyone? What's the next step? a PR to the Bridge Foundry site?

[ultrasaurus]

@aneyzberg looks great to me!