Great disappointment of the last year: No Code4LIb Fix

One of my professional disappointments of this last year was my inability to attend the wonderful Code4Lib Conference. In fact, I didn't make any conference at all. I'm going to try to make up for it next year by attending the wonderful Access 2009 conference. I've got plane tickets, registration, and some travel plans in place. Next up is to try to secure lodging this year.

Yet, I can't help but wonder what would have happened if I had the chance to go to Code4Lib 2009. I'd finally have a chance to combine two of my loves....coding and geeking out about Lovecraft. In fact, I have a feeling I might have carried it too far and would have caused something like this to happen....

Let's play Hide the API!

Howdy folks, it's been a while. But I have reached the end of my patience on a particular matter: documentation in the library vendor world. I'm bothered by both how difficult it is to find and how incomplete it usually is even when it does exist. So I'm going to quickly look over some examples and offer a plea to those creating these apis.

Citation Management: please let me enable users of YOUR product/service to actually get value from it.

One recent set of offenders were RefWorks and EndNote. They both offer "direct exports" where an end user could be on your website or catalog and choose to pass along citations to a person's refworks account. I ended up asking for help in the excellent #code4lib to even find the RefWorks documentation. I had seen it at some point but Googling and looking around their websites failed to find it again when I needed it. #code4lib provided the answer (Refworks Direct Export), but the documentation was incomplete.

Yes, I got enough to work. I had to sit and work through combinations of input formats (raw MARC, MarcXML) to the api and options to the api to even figure out combinations that worked. I'll confess. I only got it to work by seeing the University of Michigan's Vufind implementation: http://mirlyn2-beta.lib.umich.edu/. Had they offered samples of each of the import formats, that would have saved me hours of time and probably enabled me to get far enough that it would be in my catalog at this point.

There's another good reason to have good documentation that's easy to find. Even contacting their tech support I got wrong answers about what input formats could the filters take. This does not exactly make me trust your abilities and the longevity of your company. Refworks could drastically improve this by adding the examples, making sure a link to this is on their front page or at least in a page that's like "Technical documentation", and having the phrase "refworks api" somewhere in the document for indexers.

Endote was a complete failure in terms of documentation on their service, which still doesn't seem to exist. Refworks, see your opening?

Websites? Oh yeah, those are like brochures with even more pictures!

Or at least that's the impression I get from looking at library vendors sites.

Now my latest frustration. I'm trying ot find out more about the Syndetic API. You know, that thing you use to call to display cover images, table of contents, and other possibly cool stuff. At this point I'm likely to just poke at other sites and "crib" from their urls. But that doesn't let me see the full range of possibilities. But I keep looking at http://www.bowker.com/syndetics/ and failing to see anything useful. Googling for Syndetic API seems to just return a lot of related blog posts that all fail to have a link to any documentation.

I suspect in part this comes around from the fact that most of these companies seem to view the web as a place for marketing. They want people to see pretty pictures of their products. Meanwhile their developers and documentation folks probably are used to interacting with some of the big players and companies out there like say, ILS vendors, online retailers and the like. They probably have a pile of pdfs somewhere that they typically send off to one department when someone subscribes to their service.

I also suspect, as I've seen this behavior elsewhere, that there's a combination of paranoia (someone could just copy our API! Doom!) and the thought that somehow, somewhere they might be able to charge money at every point in the process. In other words, they want control about who knows about the api in the hopes of get away with charging developers to use the api and the library to use the service. If they open the api, maybe folks like Ex Libris would not get Syndetics agreement. Not that I believe this, but I suspect it's in the psychology of some of the management types who don't want to give up any control.

So I have a humble plea to all those creating apis and services that might be used by a variety of people, including small, loosely affiliated groups. Please make your documentation findable. I could probably dedicate another entire blog post on how to do this but here are some quick ideas: find out what other people actually call the api and make sure those phrases appear in the document, have a subsite just for documentation, and feature cool implementations on your front page with a discreet link to the api documentation.

Why document? Some reasons:

• Unlike proprietary systems, software development in libraries seems to be more decentralized and erratic. Cool stuff happens due to small groups who manage to get a chunk of time to work on a project. Sharing pdfs in groups like this is problematic. Having to constantly navigate through your "tech support" is frequently frustrating and counterproductive. There's lots we could be doing and we'll just choose another project.


• Sometimes there's people who do really cool stuff that aren't even on our staff. Computer science undergraduates doing mashups, library grad students trying to make a reputation for themselves, "Super patrons" who want to see cooler software in their libraries and volunteer their time.


• Many libraries play "follow the leader". Every project that successfully implements your api could very well in turn increase the number of clients you have. Trying hard to compete with one other group? If a bunch of librarians see a catalog where in one catalog you can import your search results to citation manager x but not y, they're very likely to consider getting citation manager x. In other words, it's the best free advertising. I know there's a good business school type term for this, but I fail to forget it now.


• Just having that api there increases your "buzz" factor. Software programmer types will poke around apis and daydream of what we could do with it and babble about it in blogs, IMs, and chat rooms. If there's some cool feature that no one else has implemented and you don't have it documented it does not exist. Period.


• Really, do you think that you really are in danger of having the competition get a leg up on you if you have high quality documentation? Think of this, if your competition is that aggressive, they have far more motivation to reverse-engineer your service than we probably have of even using it. So in other words, even without adequate documentation that company may figure out what you're doing, but we certainly probably will not.

While I'm talking about documentation, I've got a related rule I've held for a while that is also a useful guide. If you find that in Google and other search engines other versions of documentation of your own service is getting higher hits than yours, that's an indication you need to re-work your documentation.

A quick example is Microsoft's documentation sites. Lately I've seen some sites that have (probably illegally) copied all the content but stripped most of the annoying msdn formatting, rendering a page that much more readable.

If you're seeing a lot of tutorials, make sure to write a good tutorial and add it to your site.

In the end...

In the end I'll probably just go look and figure out what our consortium is doing in our catalog as far as the Syndetic api. Which also means my stuff will look just like everyone else's. Boring.