APIs documentation
Today I want to talk about documentation, especially about APIs documentation since it is most useful kind of it. People rarely read user documentations, FAQs and other stuff until they are in trouble. But developers read API reference before that since they couldn’t even get into trouble without it. I mean how could you call a function in a wrong manner if you don’t know how it’s called?
On the other hand API references is arguably a hardest kind of docs, it should be cross-referenced, indexed, user should be able to find a function she needs even if she doesn’t know a thing about it. It is really hard to manage. In fact I never seen an API reference that is good. Yes, even “good” level is hard to achieve. If your API is consist from 10 classes with 10 methods in each one it’s ok. I have never have a problem with haXe API reference although it lacks even slight presence of comments. Yes, you have to look in the code sometimes but it’s ok for a small code base anyway.
But when your code base grow you have to do something about documentation. You don’t want developers re-implement stuff from your library, do you? And if it is easier for them than to find a right standard function they’ll do it all the time. And will rant to you and others that API lacks all sorts of basic stuff even if it don’t. That might hurt library carma a lot.
I mean look at MSDN. Sometime ago it was reasonably good, oh, I mean so-so, tool. You could find a lot of info for any WinAPI or C++ standard function in no time, see how they related and stuff. And now… Just try find something about .NET libraries. I mean, common, that is one of most used libraries out there. It has thousands of classes, methods and so on. And if I search for a String class what do I get? “Represents text as a series of Unicode characters.” Huh, is that all? Are you kidding me? What if I have MBCS string in CP-936 encoding, how do I convert it to this string? Ok, let’s see constructors. String (SByte*). Looks nice. “Initializes a new instance of the String class to the value indicated by a pointer to an array of 8-bit signed integers. Supported by the .NET Compact Framework.” Ok. What encoding should that array of bytes be in? I mean encoding is the
most essential property of a String, it just doesn’t make sense to have a string without knowing which encoding it is in.
I think I know why that happened. It’s all Java fault. Java-doc to be precise. Yes, it is a nice feature but it wouldn’t work with any programmers. You have to make them write a good comment and they will try to avoid that as much as possible since it is just boring. I know since I also think that way, thanks god I don’t work on public API. And that is a half of the problem with .NET actually, the other one is lack of the sources. XXI century. Open source is everywhere. Java comes with sources of the library from day one. MFC was distributed with sources. How horrified should they look for .NET library that Microsoft decided not to show them? You say, ok, but it doesn’t related to documentation. But it is. What if you just happen to be in the situation when you have to know for sure what String (SByte*) does? If the sources were there you could look it up by yourself. In fact I often do that for MFC and STL and mostly for any other library I know. Just because API reference is always suck. That’s essential property of a thing.
I couldn’t say that things are better in Java world. Yes, they provide a lot more information about methods, they have sources shipped with it. But they lack of such useful search-as-you-type facility for method and class names that MSDN provides. There at least you could find a function you need. Here you couldn’t survive without google at all. Lets hope they do something similar at least on their online reference since it is really impossible without server side anyway.
I think at the end I should mention two big and honorable projects that doesn’t really care about documentation at all. Yes, they have some but it is just not developer oriented. Which is really strange for API reference, don’t you think?
One is Emacs. Yes, it has manual. But it is a mix of user oriented and developer oriented docs which makes it really hard to find a thing you’re looking for. Sources aren’t helping here much too since they are in Lisp. I’m not a Lisp developer so they hardly make sense to me.
Another one is Dojo. Great project but it is too overcomplicated. JavaScript library should be lightweight. That one just not. It has everything you ever imagined to do with JavaScript already done and tested. Except it is really hard to start using it. There is a book with simple examples that does not make it any clearer how to write more advanced ones which makes it useful for marketing not developers, api reference with less information than in MSDN, and really complicated and unnatural for JavaScript techniques that makes sources unusable. How convenient. But at least it is free and comes with the sources so it still better than .NET. Oh well, everything better than .NET anyway.