Wandering Data

I’m a developer. I often spend my days searching API documentation while doing research. A day ago, in this role, I started to get quite frustrated at the lack of details that a vendor provided – “why couldn’t they have something like our DCX?” I thought. To say that some of the classes had sparse documentation is an understatement.

When I’m looking up our docs (way too much to memorize and faster than looking it up in the code) and see something weak or confusing, I simply add a comment. If it is in my own product, I add a clarification visible to all. It’s the same as emailing our doc team and it makes the clarification available to our customers.

So where am I going with this? Following the theme of my previous post, all vendors should have a site like our DCX!

And all users of SQL Anywhere should take advantage of DCX. Don’t get me wrong, our doc team and developers who provide documentation are quite busy so a massive flood would have to be prioritized. Yet even a volume of constructive requests for clarification will help us know what sections of API are used frequently and really could benefit from improvement. While the docs themselves are not updated until the next release, we do post responses to comments when we feel they would be of benefit to the general user base.

Of course, sometimes what is needed is much more that what would be appropriate in an API reference. This is where the newsgroups and the SQL Anywhere forum (which is currently in beta) comes in. Here not only can Sybase iAnywhere staff provide answers and samples, the whole user community can share and grow to the benefit of all!

As I said, I’m a developer, and in my utopian world, all developers would have perfect documentation. In the meantime, everyone should have and use DCX-like documentation.