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.