On 16 May '08, at 7:19 AM, john darnell wrote:
Sigh. Your attitude reminds me of a conversation I once had with afellow programmer. When I was encouraging her to add more documentationto 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
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) 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: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [EMAIL PROTECTED]
