So lately my job has me working on a project with a heavy emphasis on maps. I'll forgo details but I'm dealing exclusively with MapQuest's API... and it is so incredibly frustrating.
The problem arises in the fact that I have to use the .NET SDK, which sadly has had it's support yanked. Understandably MapQuest is focusing their attention on their JavaScript and Flash APIs and moving away from the less web savvy languages of C++, Java, and C#.
As I mentioned, my application has to use the .NET SDK and documentation is incredibly sparse and terse. It's almost as if the writers of the documentation were trying their best to simply finish the project so they could move on to other areas. And truthfully I can relate to that feeling - as I'm sure almost any developer could. My issue lies in the fact that this isn't sparse documentation of a program or class that nobody else will ever see. No, these are APIs that lots of people will use.
If you don't want to document the programs you write for your own use, that's cool, more power to you. But I think if you're providing an API to developers, it's in your best interest to make that API complete - which, in my book, includes thorough documentation.
As an example, the documentation lists a whole collection of DisplayTypes. One such entry is "0054 DTR_ROAD5." What is a ROAD5 you might ask? Beats me, it's not expanded upon to give the developer a quick reference for what the DisplayTypes represent. Instead, you have to make a dummy DisplayType and toggle it on and off to see what it controls. That might not be a huge deal for one or two, but there are hundreds of DisplayTypes. A simple description of the DisplayType represents would have been extremely helpful.
So what am I getting at? Who really knows - maybe I just wanted to release some frustration. I like to document my code. I personally find that it provides me a chance to solidify and double check what I'm doing and make sure it makes sense in the context of the program. I guess I just wish MapQuest shared my affinity for commenting.
/rant
/walloftext