A while back I posted some advice for managing open source software projects effectively, so I was interested to see this post by Ed Corrrado on paying attention to the little things that can really make a difference for those trying to implement your code. I’ll summarize his points here, and comment on them, but you’ll need to go read the full post for his commentary on these points:
- Include complete install instructions. This is huge. If you fail to note a dependency, or miss a key configuration step, or assume specific knowledge on behalf of the people trying to install your code, they may fail completely.
- On your Website include (at least) basic operating instructions and screen shots. I find screen shots very helpful, even simply to convince me to download and install the software.
- Respond to posts on your forum/blog/e-mail list. If you don’t, how would anyone know that the code is being maintained?
- Keep people informed/updated. Even just a quick note to a mailing list or on a blog is a lot better than nothing.
- Treat users (even newbies) with respect. We were all noobs once, so the Golden Rule applies here as it does just about everywhere else.
While these things may seem obvious things to do to maintain a successful open source software project, they happen. They happen because some of these things can be overlooked by a busy person or team who may also have a “day job”. Or, they could be assigned a low priority and no one ever gets around to it. But as Ed points out, they can be exactly the kinds of things that prevent people from installing and using your software.
No related posts.
Hi Roy. I agree that all of the above are important and need to be there in an OS project. I also think that Ed’s piece, like much that is written about Open Source Software, could answer some of its own concerns with a slight shift in viewpoint…
Talking about “installing and using your software” is useful when talking to a vendor who is selling stuff. With OS though, even when you are a newb and dabbling, it really is “our software”. You are right that people are too busy with their day jobs to complete points 1-5, but as Ed points out: “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”.
So, to me, the answer is to stop whinging that some things are not there and start putting in your own time to fix them – or accept that this is an imperfect gift in embryo waiting for more community effort.
There are other people who are able to do points 1-5 and pointing at developers as people who should “fix” them is treating them like they are responsible for the success of the whole project, which is very reasonable if talking to a software vendor, but not in this case. I think it is unfair to judge an Open Source project as something one is “less likely to contribute back” to based on the fact that it obviously needs more people to contribute more than code to it. Catch 22 much?
Kathryn, of course you should step up and contribute if you can. Both Ed and I have been involved in open source projects and we know that. But that does not remove the responsibility of those who are distributing the code to strive to do it right. That is, assuming they actually want people to use it.
There can be any number of reasons why people can’t contribute. You don’t know the programming language, you write code too poorly to be acceptable (my particular failing), you don’t know the code well enough to write the documentation (and it takes a long time to learn it well enough if you haven’t written it), etc.
An open source project that expects people to “quit whining and fix it yourself” is no way to build an engaged community. Truly successful, long-lived open source projects have the qualities that Ed identifies above, and those seeking such status would do well to pay attention to them.
I agree that long lived and successful OS projects have the qualities above – but generally these extras came about when the projects were more mature and after a lot of people with diverse skills put themselves forward to help. OS is so different to vendor software in that it lets itself be seen warts and all before it is a fully polished product.
These things may very well prevent people from installing and using the software. I would hope that as we get more used to OSS, we have more people on staff with skills to fill in the gaps – just like we gradually had more people on our staff who knew how to create workarounds for unsatisfactory vendor software that they could not change.
I don’t think it is fair to use criteria that applies to a fully-launched vendor product or a very mature OS project and apply it to all OS projects. I think it is an unfair critique – like criticising the operating practices of a small rural branch library because it does not have an up-to-date procedure manual and its signage is a bit hoky. Especially when the library has a badly handwritten sign on the front counter saying “we need sign makers, please work with us”. (Rather forced analogy admittedly )
Asking people to fix something themselves is very different from suggesting that people put in their own time, in community, to fix something.
Kathryn, I’m sorry, but I still don’t see where open source projects should get a free pass on criticism simply because they mean well. Meaning well has never prevented me from getting criticized, and neither would I expect it to.
When I was more involved with contributing to an open source project than I am now, we would welcome feedback about issues people were having, and prioritize them for fixing. We didn’t expect our critics to jump in and fix it unless they offered. But maybe it was just the way we approached it.
I guess I don’t get why it is so unfair to hold open source software to the standards to which it should, by all rights, aspire — the items noted above as well as others. We all know it is a journey, and that no project should be expected to meet all of these standards at the first beta release.
But why is it such a problem to point out where some projects may need to improve? Would you prefer that if we can’t fix the problems ourselves that we remain mute, so that others could stumble on the same issues?
Keep in mind that specific comments will often come couched more constructively than these posts may imply. In other words, a comment may come in like “hey, this looks like a great app, but I can’t get it installed. Is there a dependency I’m missing?” Which hopefully would clue them in that their installation instructions are lacking. What Ed is (and I, in his wake) attempting to do is to identify pitfalls before they happen. So we’re lacking the “hey, this looks like a great app” part, which would at least go some way toward softening the blow.
Believe it or not, we’re on the same side. You don’t need to protect open source software from Ed or I — maybe Stephen Abram, but certainly not us.
Yeah – I know. We both mean well
My point is not that we shouldn’t criticise or offer constructive criticism to OSS projects.
It is that it is unfair to point out the admitted failings as though the people involved do not realise they are there, or overlooked them simply because they are busy.
It is unfair to say that the project needs to change what it is doing to get us to contribute without at least examining our mindset and checking whether the criteria we are judging it from is from the POV – “what should those guys do to make me want to contribute?” rather than “how can we work together to solve this?”.
I agree that an unresponsive, unwelcoming community around undocumented OSS is not ideal or going to build community. When the choice is – as so often – between releasing software that could form the basis of a great community project or not releasing it because documentation is a bit sketchy and the team do not have time to answer forum questions, then I would hope that most OSS communities would choose the former. And that most potential users would put their energy toward filling the gaps – because they can; rather than judging the software by the criteria they use to judge commercial software – where things have to be “just so” because there is no way a user can change a thing.
(I do think we are probably singing from the same hymnal though
)