Log in

Sat, Jul. 30th, 2011, 05:06 pm
A Quick Thought on Language and API References

We spend a lot of time and energy on making software usable and user-friendly, and with good reason. It only makes sense to make the computer adapt to the user, not vice versa. So why is it that we don't give this kind of attention to the tools the we as technologists use every day? When is the last time you saw a beautiful, easy-to-use language or API reference? It seems to me that there's a lot that could be done to make these gargantuan beasts easier to use. Things like configurable sort order:

  • Alphabetical is a great default, and fantastic if you know the name of what you're looking for. I fully support keeping this as the default.

  • But what about optionally sorting by subject, for when you know the thing you're looking for is in the library, but you don't know what it's called?

  • How about sorting by frequency of use? Don't show me the arcane shit that nobody but embedded programmers care about at the top of the reference just because it happens to start with 'a', show me the common stuff that everybody needs on a daily basis.

  • What about logical order of use? Show me constructors first, then mutators, then accessors, then utility functions/methods, then destructors, so that the reference document itself mimics the structure of how to actually use an object or library of functions.

Language and API references tend to be huge and difficult to use, and there's no reason at all why this should be.

Mon, Aug. 1st, 2011 12:16 pm (UTC)

In this case, I completely agree with you. I worked on a recent project documenting a new model API, and for 90% of practical applications, developers would use 4 out out of the 70+ classes to do everything. Yet, the javadoc doesn't advertise this, or even mention it. You have to follow the arcane path of implements and overwrites statements through the class labyrinth to arrive at the useful classes, and even then it's difficult to tell whether a specific class or its more general parent class are more appropriate. This uses up a lot of time, and a simple metadata weight measure for frequency or subject category would cut through that rather well.

So yes, I wish there were API docs that do that, rather than having to always go to a manual (assuming there is one) for use-cases.