|The thing I hate about open source
||[Feb. 3rd, 2008|02:30 pm]
You know. I love open source software, except for one stupid bloody little thing: Documentation. It's hardly extant.
Imagine there's a really cool, lightweight program that seems to be exactly what you're looking for, and you go to use it. How do you set it up, look for the instructions. The INSTALL file gives that standard boilerplate that you find in most opensource projects you care to name, so one glance and you think "./configure && make && make install" This may not actually be the case, but you're not going to find that out until later, or it's left to you to figure out what's up. That's why people use package management, it will install without that fuss. If you're not doing that, you're asking for trouble.
But once you get it installed, you need to figure out how to use it. Right at the moment, I'm facing two different open source products, and I can't really figure out either of them. It seems to me that unless you're born knowing how to use these things, you don't stand a snowball's chance in hell of putting these products into use, unless you really like wading in and asking the code itself what it does.
For instance, I'm looking at a demo from JADE (also, is it just me, or does the idea of enforced registration for free software seem counter to the point of free software) and I'm thinking "I know you're trying to show me some really shiny but basic multi-agent interactions, and I can see from a top level how you want this to work... But, please, dear sweet lordie, tell me HOW to do it. It's a demo and a tutorial, surely you should be telling me how to at least dip my toes in the water."
Then there's a mini-dns server called TwistedNames that looks like it's exactly what I want to use, without setting up bind. Christ, you'd think there'd be a bit more information on how to use the thing. Yet, it's considered mature enough for ubuntu to supply it from their repositories.
I guess this is why the big open source projects are well-documented. If it gets big, someone will inevitably come to documenting it, or it gets big because someone took the time to carefully document how to use their product, so it lowered to the barrier to people adopting and playing with it. I know if I was working on a job, and I was assessing the different prospects available, I'd go with the one that held my hand through getting it up and running as soon as possible because chances would be that I'd be on a deadline.
Really, maybe it's the fact that Irish colleges don't focus so much on programming as the US, maybe it's that I'm somewhat slow on the uptake of some particular philosophy of software design that means I don't need documents for something this obvious (like setting up DNS or trying to see a cool multi-agent interaction), maybe I'm just unable to pull the answers from the same ethereal network that everyone else is attuned to.
The strange thing is, I'm likely to be just as bad. Worse still, I'm not going to be that poor fucker that tries to figure out how to get something to work and write a tutorial, because if I find out how to use it, I'll probably share it with the people I work with, but beyond that, I'll be feeling pretty fucking beligerant, and very fucking unwilling to share it back with them, after them making my life that bit more difficult. Of course, this is totally contrary to the idea of open source, but given that the idea of open source software is based upon good will, they could put a little forward in showing me how their special little data format is handled, or they could show me how to get the damn thing working to show off them things that they consider to be worthwhile. If they had that, I'd help however I could, but if you expect me to pick apart the code to figure out how in the hell it works, you don't get good will back from me.
I'm sure this has been said in better and more coherent ways, but I never really realised how much of an effect it can have until now.