At its core, Measure is, for lack of a better term, a contributor relationship management system. Measure consists of easy-to-understand widgets that can be arbitrarily displayed to build dashboards. It allows you to visualize and understand how people, both as individuals and as organizations, are interacting with open source projects on GitHub. It produces metrics that focus not only on code but also on contributors.
In a future column I'll cover why I think this is an important topic, but in this edition of The Queue, I'd like to introduce six lessons we learned while building Measure.
1. Naming things is hard
As has been pointed out, naming things is hard. That's well known. A good name should be evocative and almost obvious once you've heard it, but it can't be so obvious or common that someone else is already using it or so generic that it has no meaning at all. What we learned in the context of Measure is a slightly different lesson, however. One of the two project founders liked the name at launch and the other didn't. That's still the case today; but only because each founder now has the opposite opinion than when the project was launched. As the project grew, our perceptions changed, and that nuance just confirms and compounds that "naming things is hard."
2. Simple-sounding functionality is sometimes complex, once you drill into the details
One feature request that came in early was a notification system. This seemed like useful functionality, and simple enough, so we agreed. Once we got into the implementation, we quickly realized that, while notifications themselves are indeed simple, adding a comprehensive notification system to an open source project of this nature really isn't. On one side, a flexible but comprehensive configuration methodology for defining what you want to be notified about is no easy task. On the other side, you have to decide not only which notification methods you'll support (there's email, push notifications, and myriad more) but which implementation(s) of each (which is where the complexity balloons). In short, "I'd like to send an email via SMTP when this threshold is met" is easy. "I'd like to get notified about this arbitrary thing via this arbitrary method" isn't. It's important to think through the implementation details before you agree to a feature.
3. Work closely with your dependencies and they'll be nice to you
Like most open source projects, Measure is built on top of quite a few other open source projects. One of those is GHCrawler. Early in the project, we realized GHCrawler was missing functionality that we needed, so we opened a pull request (PR) and added it. It seems simple, but often it's quicker or easier simply to add the functionality in your fork and move on. "I'll clean this up as soon as I have a chance and submit it upstream," you think to yourself. And you genuinely intend to; but it's all too easy to forget and move on. Contributing our changes back not only improved GHCrawler for everyone, but the next time we had feedback, the developers were extremely receptive. We'd built rapport with our contributions and were part of the community.
4. Your error paths are at least as important as the parts that work
This is another one that people intuitively know and understand but is easy to overlook. Inevitably, there are going to be times between when someone downloads your software and when they get it working properly, that it doesn't work as expected. If your error messages don't explain what happened and why—in a way that allows that error to be corrected—many potential users will move on. We've all experienced them, but opaque or non-existent error messages are really frustrating. Especially in the very beginning, users get more of an impression of your project from how it handles errors and fails than from how it works when everything's good.
5. Marketing matters, and marketing a project is as much a skill as writing it
Marketing can be a bit of a dirty word in the open source software community. And make no mistake, marketing when done incorrectly can be creepy or send out the wrong vibe. But if you build a better mousetrap, the world will not beat a path to your door. Stop thinking it will. You need to ensure others know about your great project so they can start using it.
6. Have a philosophy
When we started the project, we wrote down five philosophies and made them clear in the repo:
- Should be simple
- Should be visually appealing
- Should treat the concept of contributors as first-class citizens
- Should offer an opinionated default experience, but be extensible
- Should be able to completely separate inside and outside contributions
Along with the project description, this list allows people to easily understand what Measure is, what it does, and who it's for. But it does two other important things. It makes clear who Measure is not for, and it allows us to more easily say "no" to feature requests or PRs if they don't fit that philosophy. Saying "no" is never easy, but having clear guidelines on why, and doing so in a respectful manner, go a long way. While saying "yes" may be easier, attempting to merge every PR; leaving issues or PRs outstanding because you may address them some distant day in the future; or having your project try to do too many things outside its core focus are ingredients for a bad outcome.
These are six lessons we learned (or in some cases relearned) while building Measure. What lessons have you learned while maintaining an open source project?
Comments are closed.