Re: Why has the Metrowerks sign been taken down?

>> - Documentation: Apple dumped a major new OS on us virtually
>> undocumented. The state of documentation is getting better as time goes
>> on, but it is still far from ideal and it used to be all but
>> non-existent for much of what was new in Mac OS X. (Case in point: Take
>
> I don't know; I worked on Mac OS X since DP4 came out. I could find the
> documentation I needed. I asked questions on email lists when I needed.

The documentation issue is probably the single most universal complaint
I've seen on Apple's carbon-dev list over the past four years. The
issue is not whether or not you can find information or get code
written. The issue is documentation, and it hasn't been done in a
thorough and cohesive manner for Mac OS X by any stretch of the
imagination. E-mail lists are not documentation and they are not a
substitute for documentation. They're a great source for getting
questions answered, but they are not well suited for gaining a broad
understanding of technologies.

Too many people today, IMO, fail to study technologies to get a good
understanding before they write code. They grab some sample code or
find a likely looking API, learn as little as possible to get it to
compile, and then if they don't get the expected results they post a
question on some mailing list asking why it doesn't work or what API
they *should* be using. Someone answers, they change a few lines of
code and they're off to the next task. I've seen a steady stream of
such questions on the carbon-dev list for years now. I am convinced
this is not the best way to write code. It may get you working code
eventually, but working code is not synonymous with efficient,
well-designed code, or robust code.

On the contrary, it is my belief that code written without an
understanding beyond the minimum to needed to get it to work is a
significant source of bugs. All too often the programmer writes code
that works for him and he has no idea that said code *isn't* going to
work correctly if the user is using a different primary language, a
dual-processor Mac, a scroll wheel, unmounts and remounts a volume,
uses text input other than the keyboard, or any of a hundred other
things which could be different with another user. Robust, correct code
requires understanding more than what parameters you should pass to a
function and what that one specific function does. You need to
understand the big picture and for that you need real documentation.

> So our experiences don't seem to match.

Our experiences aside, the fact remains that Apple is taking *years* to
get real documentation out there, and one of the biggest single reasons
is that they won't hire enough tech pub writers. This is why so many of
the headers now contain documentation. It was taking so long for tech
pubs to get documentation out there, the engineers started documenting
directly in the headers. It was a stopgap measure implemented out of
practical necessity. Of course, the quality of said header
documentation varies widely from header to header, with some of them
providing excellent overviews and detailed remarks, and others
providing nothing.

Two or three years ago people were crediting the carbon-dev list and
Eric Schlegel in particular for the fact that they ever got a product
shipped on Mac OS X. That's just not right. We deal with it, but we
deserve better IMO. If I may indulge in a car analogy, when Chevrolet
releases new models, all of the dealer service departments get service
manuals for maintaining and repairing them. Not five years later or a
year later, but right away. What Apple has done is equivalent to
releasing a new model without service manuals and letting mechanics
figure out how to repair them through online mailing lists with other
mechanics. It's pathetic and shameful.

> And I used Carbon, Mach-O, java, Obj-C, C++, AppKit, and PB / Xcode. I even
> used makefiles, otool, and nm. Even perl... Ugh.
>
> I've also coded from Mac OS 7 on, and I find the docs for Mac OS X to actually
> be better, as they aren't all in pascal code I have to convert to C or C++ in
> my head! ;)

That doesn't make documentation better or worse. If you were using
Pascal today you would have the opposite perspective. When I started
programming == when I started programming the Mac, Pascal was much more
popular and in fact it was the language used in the introductory
programming classes at the local university here. I'd still take
documentation in Pascal over no documentation. No documentation is
essentially what we had in the beginning, and there are still
significant issues with what we have today.

If you're content to spend your time working around the problems in
Apple's documentation and tell yourself there isn't a problem, that's
your choice. But many, many of us acknowledge the problems while
working around them and really wish we didn't have to spend so much
time working around them.

Larry

.

Relevant Pages

  • Re: Why has the Metrowerks sign been taken down?
    ... > web about how apps are already compiling and working with Mac OS X ... > to do it because of the documentation. ... - Large developers like Adobe and Microsoft have direct access to help ... of Apple engineers who contribute to those lists. ...
    (comp.sys.mac.programmer.codewarrior)
  • Re: How to consolidate and sum data
    ... Mac OS X 10.5 ... so that I get the sum (total duration of all events attended) for ... I tried playing with the Data: Consolidate menu item, ... documentation on Data: Consolidate? ...
    (microsoft.public.mac.office.excel)
  • Re: Is any part of Ethernet circuitry tied to Open Firmware?
    ... things that constitute this overall problem that other Mac users are ... Apple supplies instructions for how to set up Boot Camp and Windows (XP ... with correct installation of the drivers. ... documentation, configuration or drivers for external devices are the ...
    (comp.sys.mac.system)
  • RE: [RFC] [PATCH 1/2] Driver to remember ethernet MAC values: maclist
    ... MAC ids. ... load the MAC and then set it into Ethernet driver resources ... documentation in the header file and makes the whole thing fail ...
    (Linux-Kernel)