A Quick Thought on Language and API References

[talonstrike]

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

Comments

[angry_american]

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.

-FW