OSCON talk: "Harnessing the Good Intentions of Others for your OSS Project"

I attended OSCON 2012 in Portland last week, and I saw some good talks and some bad ones. (Mine was middling -- a disappointment, but I will use what I learned to improve for the future.)

One good OSCON talk I attended was titled "Harnessing the Good Intentions of Others for your OSS Project", by Llewellyn Falco and Lynn Langit:

The idea is that there are a lot of developers out there who would love to help you, but the barriers to their entry are too high.  A potential contributor must understand your system, figure out where to make a patch, and submit it.  This is already more than the two hours or so that most people are willing to spend making a contribution to your project.  (A related point made by David Eaves at the same conference, and possibly repeated in this talk, is that when the maintainers review the patch, they usually reject it.  The main feedback to the newbie is the "invalid" status of the bug report.)  The end result is that almost no new developers ever join an open-source project.  The speakers claim to have a 98% conversion rate (though I am not sure how meaningful that statistic is) and shared their approach.

Here are three key points I took away from it.

1. Listen for feedback and problems.  The speakers suggested setting up a Twitter search (you can get an RSS stream or a Google alert), and also searching StackOverflow and blogs.  Whenever you get a comment, repsond quickly -- definitely within two days, and usually faster because after two days the person has completely moved on from the issue.  It may seem overwhelming to look in so many places for buzz or anti-buzz about your product, but start small and build up as you build your developer base.

2. Pair Programming.  Whenever you get a communication with another developer, offer to pair program and don't stop asking until the other person agrees.  This can compress the other developer's learning time into the two hours they are likely to be willing to spend, and the other developer is much less likely to become frustrated or confused.  It can also help you to understand the patch.  A speaker recounted that he hated one proposed patch because it wasn't elegant and didn't fit into the system's intended design.  Rather than just rejecting it, he pair programmed with the proposer and after a while realized that his system was architected in a way that prevented any cleaner, better solution.  So he accepted the patch, and that patch has been important for his community of users.

When pair programming, start with the camera on for a few minutes to establish a personal connection.  Then, after that, go voice-only and use screen sharing.  Even Skype's crummy screen sharing works pretty well, and other systems like join.me are even better, especially ones that let you share the keyboard and mouse as well as the screen.

The "98% conversion rate" statistic was very fuzzy to me.  I suspect it is the percentage of pairing sessions that eventually led to at least one commit by someone.  I would find it hard to believe as the number of developers who became active in the project.  I wish the presenters had been more clear and upfront about this, because it felt like they were misleading or overselling.

A downside is that pair programming is an incredibly time-consuming approach:  it's hard to imagine spending multiple hours for each communication that comes to an open-source project.  The speakers don't consider this work:  they enjoy pair programming so it is just fun.  Furthermore, the potential benefit from a fix for an important bug or from attracting a new developer may be very large, so significant time investment is worthwhile.

3. Action items.  In any presentation, your final slide should contain a single, specific action for someone to take.  One speaker recounted that when he started putting a download button on his talks, his downloads went up a lot.

Cold, rainy Seattle

Three times a week, I walk across campus to class.  After 8 weeks of the quarter, I have worn a jacket exactly once, because it is generally dry and warm enough to do without a jacket.

To be completely fair, I missed a few days due to travel and I don't know how the weather was then.  And, on some of days it rained at other times, such as overnight, which keeps the region green but doesn't mar our enjoyment of it.  Finally, at least once it was misting outside, but not enough to justify a jacket.  Some days it was overcast, on others gloriously sunny.

Seattle has an undeserved reputation for non-stop precipitation.  A popular joke says "It only rains once a year in Seattle, but it lasts 9 months."  In reality, Seattle doesn't get very much rain.

Java type annotations: early draft review

The type annotations specification ("JSR 308") is in Early Draft Review.  This is an opportunity for the public to comment on the proposed specification, so that it can be improved before being incorporated in the Java language.

Oracle has announced that they intend to include, in JDK 8, support for type annotations.  Currently, Java only permits annotations, such as @Deprecated or @Override, to be written on declarations.  The ability to write annotations on type uses enables improved documentation and bug detection.  One example use is the Checker Framework for pluggable typechecking.  Note that the Checker Framework is a third-party tool and not part of the Java language proper.

Overcoming writer's block

I have added a new section, "Getting started: overcoming writer's block and procrastination", to my popular advice for writing a technical paper.

Command-line option argument processing in Java

If your program processes command-line options, then you have to write duplicative, boilerplate code and documentation:

• to parse command-line options and set variables in your program,
• for usage messages (such as printed by a --help option), and
• for documentation in the program's manual and/or manpage.

It is a pain to write all this code.  Furthermore, it is easy for the different representations of data about command-line options to get out of sync, which leads to bugs and user confusion.

When you are writing in Java, a better approach is the Options class of plume-lib.  If you use the plume.Options class, you do not have to write any code, only declare and document variables.  For each field that you want to set from a command-line argument, you write Javadoc and an @Option annotation.  Then, field is is automatically set from a command-line option of the same name, and usage messages and printed documentation are generated automatically.

This class has been in daily use for well over five years and is slowly gaining adherents, but it still pains me when I see code that duplicates command-line logic and documentation.  This includes most other solutions I am aware of, including Apache Commons CLI.  It is, however, similar to args4j, which seems to have been independently conceived around the same time as this class.  Use whichever one you find more convenient and useful.

For full usage information, see the plume.Options documentation.

Please don't make me read my email during your presentation

When I go to a conference, I typically find the "hallway track" to be most rewarding:  technical conversations with colleagues whom I don't often get to see.  This is something that I can't get from reading the papers in the conference proceedings.

Nonetheless, I also look forward to attending the technical sessions.  Oftentimes the presentation offers a different spin on the material than the paper does.  The authors have had more time to think about their approach and how to explain it, or the time constraints may force them to focus on the most important and high-level ideas.  (A presentation cannot and should not try to convey all the detail that a technical paper does.)

Unfortunately, I am sometimes disappointed by the quality of the conference talk, and I end up zoning out, looking over the program to decide what talks to attend next, or even -- and I shudder to admit it -- reading my email, since my inbox always get out of control while I am traveling.  But, I would much rather be paying attention to a talk that conveys insight in an engaging way!

(The audience's first responsibility is to the speaker.  An audience member who gets distracted gets less from the talk, too.  Even watching a bad talk can give value if you devote your full attention to it.  But if you lose the thread, it's very hard to regain it, and then the audience member has an even better incentive to stay distracted.  If the beginning of the talk is good or even mediocre, then this negative spiral never occurs.)

I am perplexed by why people don't spend more time preparing and giving excellent talks at conferences.  The rules for doing so are relatively simple, and are well-explained in a variety of locations, including my own article about giving a technical talk.

There's no question that it takes significant time to produce a quality talk.  For example, you have to think deeply about how to present the material, which is different than the best way to present it in a paper (though this increases your impact).  Additionally, you have to do multiple practice talks (many more than you think you need!) to hone how you present your message.  But, the results are well worth the effort.  The effort is small compared to the amount of time spent on the research and on writing the paper.  You are likely to understand your own work better after preparing a good talk.  And, you have the attention of a lot of smart, interested people who want to hear about your work and may make their impression of you and your work based on your talk.

So, work hard on your talks.  Audiences will be grateful, and it will also pay off in other ways.

Verification Games work mentioned on Wired "Danger Room" blog

Formal verification is typically a tedious and costly affair performed by highly-trained and highly-paid engineers. We would like to change that, making it as fun as a game and accessible to people without any knowledge of computer science. We would like people to prove properties of programs while they wait for the bus, by playing a game on their phones.

To that end, we are creating a system, which we call Verification Games, to crowd-source program verification. Our system takes as input a program, and produces as output a game. When a person finishes a level of the game, then the final configuration of board elements can be translated into a proof of a property about the program. Then, the player can move on to a different level, which corresponds to a different property about the program, or a property about a different program.

Wired's Danger Room blog recently mentioned this work (see the end of the article). The DARPA slide has a screenshot of our game Pipe Jam. DARPA has announced a new Crowd-Sourced Formal Verification program that is inspired by our work.