Little Things Matter

Dear Open Source Software developer,

Little things matter. If you want me to take your project serious, doing the little things right can make a big difference. Here are just a few things you should try to do, IMHO. I know that some of these are not as fun as coding in your favorite programming language, but if they aren’t done, your project will less likely be chosen for me to use, and possibly contribute back. Instead of making a long list, I will give you my five of my pet peeves about Open Source projects. These are some little things that I have seen with a number of projects that could easily be rectified.

  1. Include complete install instructions. Don’t assume people know what you mean by things like create a database and grant CREATE, UPDATE, DROP, etc. means. Just tell people how to do it. People with more skills can read between the lines if they want to do it differently. You need to design documentation for people who are just learning. Also, don’t make me download the whole package to see the instructions. I tried to use one project that had instructions for install the project on MySQL/Linux but was written on Solaris/Postgres. I naively assumed that they actually tested the Linux instructions. Wrong! After struggling with it for a day, I e-mailed the project’s list and learned they weren’t even tested ans I should use Solaris/Postgres. I have nothing against Solaris/Postgres, but it would have been nice to know I should use it before wasting a day following instructions that weren’t even tested. I went elsewhere even though I would have probably used the project on Solaris/Postgres if I knew that in the begining.
  2. On your Website include (at least) basic operating instructions and screen shots. I recently saw an announcement for a new Open Source project that I thought sounded interesting, but when I went to the URL and it was basically just a place to download the code. I at least want some idea what it looks like and what it does beside being a statistics package, a time management package, or _____.
  3. Respond to posts on your forum/blog/e-mail list. Nothing screams dead project like questions and inquiries not being answered. It is possible they are answered in private, but someone investigating your project won’t know that. If it is asked in public, answer it in public or at least post something saying you contacted the person privately).
  4. Keep people informed/updated. I went to a OSS project Web site last week and found a new version of the software to download posted about a month ago with absolutely no mention of how they got there or what was different about the new version from earlier versions. A quick post saying new files are available would have been nice. The same project’s home page says beta software for a new version is coming in Spring 2009 (it is now Summer 2010!). I think the beta version was actually version 1.1 and was posted in March, but who knows? Even if you are not actively releasing new code, a blog post with a hint or tip every now and then will add confidence.
  5. Treat users (even newbies) with respect.
  6. Not everyone is an expert with Open Source, but you should treat them with respect. If they ask a dumb question don’t attack them, ask them for more information in a friendly manner Karl Fogel in Producing Open Source Software describes this as treating every user as a potential volunteer. He writes:

    A corollary of this is that developers should not express anger at people who file well-intended but vague bug reports. This is one of my personal pet peeves; I see developers do it all the time on various open source mailing lists, and the harm it does is palpable. Some hapless newbie will post a useless report:

    “Hi, I can’t get Scanley to run. Every time I start it up, it just errors. Is anyone else seeing this problem?”

    Some developer—who has seen this kind of report a thousand times, and hasn’t stopped to think that the newbie has not—will respond like this:

    “What are we supposed to do with so little information? Sheesh. Give us at least some details, like the version of Scanley, your operating system, and the error.”

    This developer has failed to see things from the user’s point of view, and also failed to consider the effect such a reaction might have on all the other people watching the exchange. Naturally a user who has no programming experience, and no prior experience reporting bugs, will not know how to write a bug report. What is the right way to handle such a person? Educate them! And do it in such a way that they come back for more:

    “Sorry you’re having trouble. We’ll need more information in order to figure out what’s happening here. Please tell us the version of Scanley, your operating system, and the exact text of the error. The very best thing you can do is send a transcript showing the exact commands you ran, and the output they produced. See http://www.scanley.org/how_to_report_a_bug.html for more.”

    This way of responding is far more effective at extracting the needed information from the user, because it is written to the user’s point of view.

    These are just a few things that I think, if followed, will give a project a much better chance of being successful. Also, by doing this you may have a better chance of growing community who can assist with things like documentation and answering questions from other users.

    Sincerely,

    Me

    P.S. Anyone have their own pet peeves to share?

1 Comment

  1. MJ Ray said,

    August 27, 2010 at 11:08:04

    I agree with all of those except the first. Detailed installation instructions that cope with all the many varied possibilities are a lot of work are almost impossible to complete, let alone keep up to date. We’re a project to produce software, so we have to write “install thisfile.sql into your mySQL database” and leave it to you to know how to do that in your version of phpmyadmin or the mysql command-line client or ask the right project/forum for help on it. If someone sends a question, we’ll try to answer it, or if someone sends detailed instructions, we’ll try to point people towards them.

    Otherwise, we’ll spend all our time writing instructions and no time writing other software.

    After all, when maths instructions say “multiple this by tan 60 deg”, it’s unreasonable to expect them to explain how to do that on every model of calculator. Similar problem.

    Anyway, I feel the rest are fair points.