Lack of documentation in OSX
10.3 has a theoretically very cool API that will solve a lot of problems regarding controlling/managing internet connections for developers, called SCNetworkConnection. Unfortunately it's barely documented. By that I mean there is zero documentation.
There are other examples of this kind of thing, just looking at 10.3... like diskarbitrationd, a neat little daemon for handling disk mounting and the like. It's man page barely gives you an idea of what it does. Or scutil.
I'm just ranting about 10.3 stuff, but lack of documentation has been a bit of a joke for a long, long time. It's a real problem, and I can't imagine the frustration I'd have if I was messing with this stuff full time.
If you're not a developer, you can sort of get an idea of that frustration they have to deal with by looking at Apple's help system. Barely functional, and far from informative.
I'm having to dive into PPLib, but guess what... Apple says its not supported, and could go away at any time, so use the newer API for everything, which isn't documented.
Sucky. This isn't some shareware product, we're simply talking quality and polish. And it's been such an ongoing problem, version-to-version, year-after-year, that you have to reach the conclusion that it just isn't a priority for Apple.
The worst excuse I've heard is "Would you rather have the programmer writing documentation, or writing new code?" which is such a circular argument as to never be valid.
Posted by drunkenbatmanFebruary 07, 2004, at 06:26 PM
I thought part of Proper Development Process involved the developers commenting their code, code review, technical writers going over the whole mess, etceteras.
They might be slacking off on the OS, but their pro-grade productivity apps have pretty good documentation. Functionality is another story, as you've noted elsewhere.
As for Apple's patheticass help viewer... how long have they been shipping a "help" key on the keyboard? When did it stop calling up the help system?
Beyond accidentally activating it (an instant reminder as to why I ignore it), I haven't bothered with the OS X help viewer (nevermind the man pages) since the Public Beta, when the damned thing tried to connect to the internet in order to download manual entries that would tell me how I could - get this - connect to the internet.
Whee.