Re: troubling article : a few real argument of my own.
Re: troubling article : a few real argument of my own.
- Subject: Re: troubling article : a few real argument of my own.
- From: Jay Vaughan <email@hidden>
- Date: Wed, 11 Jun 2003 17:40:37 +0200
I would have to agree with Jay on this. As a veteran programmer nothing is
more frustrating than having to manually search through documentation which
is not organized very well. But the real heartbreak is.. when you finally
find it and there is nothing there but the name of the function and a couple
of abstract sentences.
That is the absolute worst.
("Shit, did I stumble across old/stale data? Do I keep looking, in
case there's something better somewhere else?" ... the dir tree
layout doesn't promote *certainty* that I got the docs I was looking
for, either... maybe there's something else, somewhere else...)
All documentation problems aside, Apple should just *FINISH* the docs
first, and then worry about organizing them later.
I think Apple should step back and consider that the
people trying to use this stuff are NOT the people who developed it. It has
been an exasperating journey so far and the limited example code and poorly
organized, incomplete docs are no help. Hate to say this but at least ONE of
the folks at Apple should buy VC and MSDN and take a look at that ...
Yeah, but please oh please oh please don't give us an MSDN, Apple.
MSDN is what made me switch in the first place. Well, it was the
final straw, anyway.
The Delphi way of doing online API documentation, lookup, and
searching, is still yet to be beat, imho. Apple engineers would do
well to have a look at that, particularly if they're responsible for
documentation ...
Still, though, I gotta say that as days go by, a DocBook -> man page
convertor seems sexier and sexier ... :) "man -k NSCoder".
--
;
Jay Vaughan
r&d>>music:technology:synthesizers - www.access-music.de/
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.