Re: Guidance for Cocoa's steep learning curve
Re: Guidance for Cocoa's steep learning curve
- Subject: Re: Guidance for Cocoa's steep learning curve
- From: Jens Alfke <email@hidden>
- Date: Fri, 16 May 2008 07:50:43 -0700
On 16 May '08, at 7:19 AM, john darnell wrote:
Sigh. Your attitude reminds me of a conversation I once had with a
fellow programmer. When I was encouraging her to add more
documentation
to the code, she replied, jokingly, "If it was hard for me to write,
then it should be hard for them to read."
The sad thing is that you are not joking...
OK, this is getting somewhat offensive. Most of Apple's developer
documentation is written by full-time tech writers, with extensive
consultation and review from the engineers involved in the code. I
know some of these writers, and I've been involved in many doc
planning and review meetings over the years.
Any deficiencies in clarity or accuracy are the result of a simple
lack of time or resources. To assume that they're somehow deliberate
is a symptom of the common engineer arrogance that assumes that any
problem you're not directly involved in solving is "trivial" and that
its persistence is only due to incompetence or maliciousness. That is
a bullshit attitude. Don't perpetuate it.
Face it: programming is hard. Programming very sophisticated complex
things like GUIs is very hard. Frameworks make that job a lot less
hard [if you doubt this, go and read the old '80s "Inside Mac" I...V
sometime!], but there are still a lot of concepts and details to
learn, and many times their topology does not reduce to a directed
acyclic graph (i.e. you can't present them in order without forward
references.)
Also face it: Most of the other software docs in the world are much
harder to follow, because most companies/projects can't afford to pay
full-time tech writers. There are a lot of amazing open source
libraries, but for the most part you are going to have to put some
serious effort into figuring out how to use them. That's not (usually)
because anyone deliberately made them hard to follow; it's just part
of the territory. We are programmers because we are good at figuring
out and navigating through complex abstract systems.
Apple's docs are very good these days, but they're not pitched at the
level of "Cocoa 4 Teh Dummiez!!1". That's not Apple's job. There are
enough 3rd party Cocoa books by now that I'm sure there are ones at
that level; anyone finding the Apple docs inadequate should go look
into these. (Yes, this might require spending some money. Deal with
it. We all got into computer programming to make the big bucks, right?)
—Jens
Attachment:
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden