Open Source New Years Resolutions

[melodykramer]

We're setting goals for increasing community involvement and reuse of our open source work. Here's an open thread for suggestions about these goals (feel free to comment), and we also have a goal to post updates here to track our progress. Some questions we have for readers both inside and outside government: Are these goals missing any important parts? If you're an outside-18F potential, current, or past contributor to 18F projects, do you have any specific needs/questions that aren't addressed here and that we should keep in mind? What would help you reuse 18F's projects for your own government or non-government work?

Our resolutions:

• Develop a set of metrics to determine what progress looks like, and how to define and measure that progress.
• Improve our documentation. We plan to make both existing and new documentation more informative and user-centric, to help people get started working on our projects. As part of this, we want to make sure people know that identifying and reporting documentation issues (and other problems) are substantial ways to help with an open source project. Non-code contributions are valuable, and we can be more explicit about how to contribute after finding a bug or error.
• Communicate our needs by figuring out better ways to ask for help. We want to be more explicit and vocal about expressing our needs and publicly identifying ways people can help out. It's important to us that the public can easily contribute to our projects, but it's not an essential part of getting our work done, so we need to figure out how to fit supporting this into our routines. We don't routinely test our installation instructions for usability, for instance — but we could specifically ask for external help with that task.
• To that end, we might use our newsletter as a way to explicitly ask for help. For example, we could include three specific open issues in each newsletter that the public could jump in on.
• Make it easy to contribute and use the libraries and tools we’ve made. We build a lot of tools that could be really useful for people who work at a variety of organizations. We can surface those tools, write about them more, and identify the parts of our work that are generic. Decoupling them from the applications we developed them for will make it easier for others to reuse them. (h/t @konklone )
• Learn from previous contributors. We’d like to reach out to previous contributors to see what they liked and didn’t like. If they contributed once and never returned, we’d like to find out why. Are there ways we can invite them back? (h/t @maya)
• Make it worthwhile to contribute. Unpaid work on government projects is public service, requiring time, effort, and skill, and we want to respect that. How can we help people find tasks that help them accomplish their goals, such as practicing a skill or doing something they’re proud of? How can we improve the timeliness of our responses while also getting our core work done? What are meaningful ways to thank people for their work, without creating a lot of overhead and while adhering to government regulations concerning endorsements?
• Run internal trainings on topics like "Basic open source community management," "How to handle a well-meaning but not helpful contribution in a friendly and positive way," and "The philosophical principles and cultural history of free and open source software." (If we do this, we'll share our notes publicly.)
• We want to better advise our new hires on open source community etiquette. For example, you should always explain why you're closing an issue or pull request — and we shouldn't expect new hires to know that on their first day. (h/t @leahbannon)
• Address user needs. Here’s a specific user need: "I have a lot of experience with open source, and I heard about 18F. Can you explain how I can help? How is 18F different from what I'm used to? What does 18F need most from me? What would it most welcome?" We plan to answer these questions in a future blog post and add it to our style guide. (Other ideas for blog posts: "You're new to open source: start here." And then another one: "You're beyond new to open source: where to start.")
• Treat this as an agile, iterative project and report back on what's working and what we can improve. We'll be updating you throughout the year on this blog, in our newsletter, and on Twitter.

[toolness]

This looks great! One suggestion I have regarding Make it worthwhile is to publicly thank contributors for their efforts. For instance, Mozilla has a section of their weekly public meetings called Friends of the Tree (here's an example). Publicly thanking contributors in the 18F newsletter could be cool--though I have no idea how any of this potentially conflicts with government regulations concerning endorsements...

Also, regarding Develop a set of metrics, you might find the Mozilla Contributor / Contribution Analysis Project useful. In particular, response time has generally been viewed as the single biggest influence on contributor retention:

Contributors whose contribution is acknowledged within the first two days - even if it is only to thank the contributor and say when it will be reviewed - will generally return to make a second contribution; wait two weeks, and they will not.

[thebenedict]

This point resonates:

It's important to us that the public can easily contribute to our projects, but it's not an essential part of getting our work done, so we need to figure out how to fit supporting this into our routines.

I contributed to C2 a while back and it was a positive experience. @phirefly took time to help me get oriented on Slack and tracker, I got quick feedback from the team and the PR was merged shortly after.

Then there wasn't an obvious next step. I don't blame the team for this at all, but it's difficult to understand what would have been most helpful. I'm an intermediate developer contributing to learn more about 18F and how good teams build software. Since I don't personally have a need for software to mange Federal procurements :smile_cat:, and most of the stories in tracker at the time looked like they required some internal context (e.g. many were specific client requests), I left it there.

Maybe this is as it should be! I don't know if it's reasonable to expect a product team to spend time curating outsider-friendly chunks of work during a client engagement. But if there were a more obvious opportunity to keep going I probably would have.

Also worth mentioning: It's possible that C2 is just not the right fit for me, but discoverability is a little tough. Even with the repos on github it's hard to efficiently answer the question "I have skills X and interests Y, how can I best help 18F?" The public Slack channels are great for project context but the single-channel approach makes it hard to browse and figure out where you fit in.

Thanks very much for your work on improving the process. It's already quite good overall.

[melodykramer]

Thanks @toolness - I hadn't seen the Mozilla meeting notes and really like them, in addition to the contributor project. I wish there was a way that I could see:

• number of new commenters / contributors to 18F projects in last 24 hours
• analytics for contributors outside of 18F

I know I could look at pull requests and forks, but there's really no way to measure comments from outside contributors (and not everyone who contributes codes...)

@thebenedict That's very helpful feedback. One thing we're thinking is that we surface our tools in a better way. Many of our tools are reusable by any organization but not a lot of people know about them. I'm currently designing a dashboard with some others at 18F to help with this.

[toolness]

Cool, glad my comments were helpful!

I think the GitHub API could be used to get a lot of the statistics you need--especially if all 18f employees have some kind of criteria that's easy to query for (e.g. membership in the github 18f org). Are there any avenues of contribution you'd like to measure that don't go through GitHub?

[melodykramer]

@brittag can you think of any avenues of contributions we want to measure that aren't available through GH data? I can't off the top of my head.

[awfrancisco]

Additional discussion happening over at Hacker News. Putting the link here so we can go back and capture anything useful that comes out of that thread. https://news.ycombinator.com/item?id=10903446

[jessieay]

Communicate our needs by figuring out better ways to ask for help.

One challenge 18F must deal with w/r/t open source is that people usually contribute to open source for selfish reasons. At least I do. When I submit a bug fix or feature to an open source library, it is always because of something that I saw was broken or needed when using that library.

Most of our code, at this point at least, is not for use by the general public, so there are few selfish reason for people outside of gov to contribute. I am guessing that people are mostly finding opportunities to contribute by surfing GitHub and diving into code. That's a lot of upfront work for someone who is operating out of the kindness of their heart!

Perhaps a way to surface opportunities for contributions would be to create some type of integration with the Dashboard. Maybe encourage projects to add github issues for open source opps and then link to them in the Dashboard / in the project README?

[melodykramer]

:+1: @jessieay - I'm on the dashboard project and this is exactly what we're thinking.

[andrewhoppin]

@melodykramer as 18F matures, I'd love to see some published guidelines based on accrued implementation experience about the realities of ongoing support, maintenance, and reuse of government-funded open source projects. I have a concern that custom built-to-order government code projects that are awesome for their initial implementor and are released under open source license often fall short in terms of actually delivering easy maintenance with long-term total cost of ownership savings, and even more in re: actual practical open source reuse by other governments.

My personal solution to this, while not a panacea, is to build open source "products" on top of large-scale high-level open source frameworks like Drupal and Wordpress that have readily available commercial support from multiple vendors, and demonstrable long-term sustainability as developer communities. The higher in the stack you can achieve that, IMO, the more open source benefit you can leverage.

I think it'd be great if 18F can help government software customers that believe in open source to be more savvy about these nuances, so that the open code that results from their investments actually realizes the open source promise of a) reusability at lower marginal cost/effort than developing/buying anew, b) flexible support/maintenance options from a diverse array of vendors avoiding lock-in, and c) the inherent innovation potential of being able to change... anything.

[brittag]

@andrewhoppin I'm curious too about how to maximize reuse of government open source projects (it usually doesn't happen automatically when people just release code; there's a range of skills and types of work involved in planning for reuse and supporting it). I've been personally excited to work on the eRegulations project since it's a working example of a custom open source project built by one agency (CFPB) that's getting reused and adapted by 18F for other agencies (including ATF). There's a short post about an early stage of that reuse, and I hope we'll write more blog posts about that story.