On paper I agree, from the other side of the fence, here is what the process looks like:
This looks good for what we want to do, let's test it out.
Cryptic error.
Google for 24h for a solution, can't find one.
Ask on official mailing list / forum / bug tracker.
Getting ignored as usual, or dismissed rudely.
Never use that product ever again.
I'm a CTO and I do that process more often that I would want to, sometimes I don't get that far because Install instruction sucks, and usually that's enough to deter me.
A concrete example: Since The Guardian opened Scribe (their CMS WYSIWYG editor) I had it in the back of my mind for weeks because it looked really interesting and close to what I had been looking for. We were doing CMS upgrades recently, so I wanted to take the occasion to plug in Scribe.
It took only 2h for me to put Scribe on my "never use ever again" list. It all look pretty neat at glance, quick install, nice plugin system, yadda yadda,... However, their one line install simply doesn't work, their is no list of dependencies anywhere, and simply no documentation. Logged an issue notifying them of the poor quality of their setup instructions. Got a reply 7 days later, which starts a discussion. But now it's too late, still have personal interest for Scribe, however my company has already moved on.
I'm all for OpenSource, have some myself (though, more of a "here is what I did recently" type of guy), however if you want to pretend to be a serious library/framework/piece of software, that includes decent documentation with clear install instruction for most common distributions.
Plus, dialogue is good, but most of the time I need it right now, or in a very short time frame, so more often that not I will simply drop back to another less interesting piece of library (or nasty one) that simply works, because that is what matters, it works when I need it. (Again with the Scribe example, no matter how much I dislike TinyMCE, I ended up using it, because one line of JavaScript is all it took for it to work).
I absolutely agree and this is a problem that a lot of open source projects face (Haraka is not alone in this). In part it comes down to the fact that most open source isn't worked on full-time, and so documentation often takes a back seat to getting your feature-du-jour working.
But absolutely we could all use some improvement in these areas.
Yeah, just to be clear I'm not bitching at maintainers, just giving the perspective of a potential company wanting to use a library. Though usually I do try to follow up if I think the software/lib is really nice, but it's often on a personal level, not for my company.
Documentation is pretty boring to write,and not as fun as feature-du-jour, but may be there could be some guidelines about what a basic documentation should have, specially with GitHub it could be straight forward to have a Markdown template for basic doc (Installation, FAQ, Requirements, Contact points, ...), I know I use one.
This looks good for what we want to do, let's test it out. Cryptic error. Google for 24h for a solution, can't find one. Ask on official mailing list / forum / bug tracker. Getting ignored as usual, or dismissed rudely. Never use that product ever again.
I'm a CTO and I do that process more often that I would want to, sometimes I don't get that far because Install instruction sucks, and usually that's enough to deter me.
A concrete example: Since The Guardian opened Scribe (their CMS WYSIWYG editor) I had it in the back of my mind for weeks because it looked really interesting and close to what I had been looking for. We were doing CMS upgrades recently, so I wanted to take the occasion to plug in Scribe.
It took only 2h for me to put Scribe on my "never use ever again" list. It all look pretty neat at glance, quick install, nice plugin system, yadda yadda,... However, their one line install simply doesn't work, their is no list of dependencies anywhere, and simply no documentation. Logged an issue notifying them of the poor quality of their setup instructions. Got a reply 7 days later, which starts a discussion. But now it's too late, still have personal interest for Scribe, however my company has already moved on.
I'm all for OpenSource, have some myself (though, more of a "here is what I did recently" type of guy), however if you want to pretend to be a serious library/framework/piece of software, that includes decent documentation with clear install instruction for most common distributions.
Plus, dialogue is good, but most of the time I need it right now, or in a very short time frame, so more often that not I will simply drop back to another less interesting piece of library (or nasty one) that simply works, because that is what matters, it works when I need it. (Again with the Scribe example, no matter how much I dislike TinyMCE, I ended up using it, because one line of JavaScript is all it took for it to work).