The joys of open source

[jducoeur]

I'm finally getting started on the LiveJournal integration, now that CommYou's IM capabilities are beginning to hum fairly nicely. First step is making OpenID work.

In theory, this is straightforward: as so often, there's already a fairly complete-looking Java library for OpenID out there, under an Apache License that I can work with. So I installed that Friday, set things up very similarly to the example code -- and not only does it not work, it fails really badly and strangely.

Fortunately, after tearing my hair out for a few hours, I came across a message from Thursday on the related Google Group, from someone else who is about two days ahead of me on the hair-pulling. This got a response of, essentially, "Oh, yeah, the sample code in the release is totally broken. Go get the current version from SVN instead."

On the one hand, I appreciate the prompt response, and I have reasonable hope that it will get me past my mysteries. OTOH, I do, once again, find myself longing slightly for libraries that come from places with persnickety QA departments. Say what you will about Microsoft (and heaven knows I can tell my share of MS horror stories), I don't think I've ever gotten anything quite *that* broken from them. Open source is lovely, and usually way ahead of the curve in terms of functionality, but the implied "use at your own risk" is biting me on the ass fairly often on this project...

Comments

[doubleplus.livejournal.com]

I agree for the most part, but the Exchange developer stuff (which I currently have the misfortune to be working with) seems to have a secret tunnel past the QA department. In addition to tools that kinda-sorta work if you don't kick them too hard, there are tools that only work with one version but have no docs telling you that, multiple utility scripts with the same name but different parameters and overlapping functionality, required .NET assemblies that for no obvious reason you have to build yourself from pre-.NET libraries...

But I've ranted about this before. Definitely the exception, not the rule.

I couldn't imagine using most open-source libraries without having Google to make up for the lack of documentation.

[jducoeur]

Actually, it's not so much Google as the communities that make up for the documentation gap. Most decent OS libraries have people you can ask when things go bad. (Which Microsoft, by and large, doesn't have any more, although I do remember the old days when we could phone their developers directly.)

And it's true that, if I think hard, I can come up with some real doozies on MS side. Sandcastle, in particular (the .NET equivalent of javadoc, essentially), is incredibly important and remarkably amateurish. Far as I can tell, it's an internal tool that got made visible to the outside when the really great OS project to fill that niche, NDoc, folded due to lack of support. But as you say, these are the exceptions...

[laurion]

This ties into the ever present 'Beta' tag we're seeing on almost everything online these days. Developers, especially those working out of a labor of love, and not out of a profit margin, are increasingly unwilling to bear the responsibility of what happens as a result of those labors fruits. Heck, even GMail is still 'Beta'.

Does anyone remember when Beta was just a letter of the Greek Alphabet, and not an implicit contract that you're on your own?

[goldsquare.livejournal.com]

Gosh, yes.

I remember one job where I was doing QA on an open API library - and not one of the examples in the manual would compile or execute, nor were they terribly illustrative.

I wrote an entirely NEW example set - one program that would compile from end to end, and which called every API in an illustrative order, with subroutines that wrapped each call or call/pair so it could be show separately.

Thing of beauty.

Documentation told me they didn't want to fight with development over the examples that they'd provided, so we were going to ship what we had.

I gave my example to sales, and also to our crew that packaged things for delivery - and it was quietly added to the examples directory on the media we shipped.

What else could I do?

[jducoeur]

*Sigh*. Yeah, the only thing that gets shorter shrift than documentation is examples. I hate it when that happens...

[crschmidt.livejournal.com]

OpenLayers actually has more going for it in the examples department than the documentation department, I expect. They're even nice and searchable by title/description these days:

http://openlayers.org/dev/examples/

I wish users would tell us more of what they didn't see in the examples: they usually only come to us when they have some super-complex application, and never bother to say "I could have used an example to do $foo".

[jducoeur]

Quite nice -- good to see a project that has clearly made examples a major priority...