Cocoa mail archive
Re: Guidance for Cocoa's steep learning curve
FROM : Jens Alfke
DATE : Fri May 16 16:50:43 2008
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
DATE : Fri May 16 16:50:43 2008
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
