The challenges of documenting Cocoa
The challenges of documenting Cocoa
- Subject: The challenges of documenting Cocoa
- From: Erik Buck <email@hidden>
- Date: Sun, 19 Aug 2007 15:08:41 -0700 (PDT)
As an author of a 1000+ page book about Cocoa programming, I have an opinion about the trade-offs that must be considered when documenting a large framework. The potential audience for a computer programming documentation can range from beginners who dont know what a compiler is to people who are experts themselves and just want a quick reference. Beginners are frustrated when prerequisite knowledge is assumed, and experts are frustrated when they have to search through redundant introductory material in order to find the nugget they seek.
In the middle of that spectrum are programmers who are expert users of other frameworks. These programmers often want a quick translation guide. I would do such and such this way using that framework; how can I do it with Cocoa Sometimes we even see programmers in the various forums complain that Cocoa works differently than some other framework. I dont know how to respond to that other than say, Yup, Cocoa works differently than that.
Authors have an additional challenge when writing on-line documentation. With a printed book, it is usually safe to assume that readers start at the beginning or will at least flip back a few chapters if they get lost. Readers come to on-line documentation in seemingly random order. A single search might identify twenty pages of information at various points along the spectrum from beginner to expert. The odds are _not_ in the authors favor that readers will understand the prerequisites and context needed to understand a page found at random. Once again, a newbie who chances upon expert level documentation will be frustrated and report that the documentation isnt helpful. An expert who finds extremely introductory information will complain that the documentation is too bulky and its too hard to find information.
Cocoa presents yet another challenge. In most respects, Cocoa is not an al-la-cart framework. There are key design patterns, repeated idioms, optional conventions, and most importantly some essential conventions. No matter how much experience a programmer may have, if the programmer fails to adhere to essential conventions (like Cocoa memory management conventions), they will not succeed with Cocoa. It is common that an experienced programmer will get started by searching Apples on-line documentation and miss critical details. A symptom of this phenomenon is a mailing list post asking if or claiming that NSMutableDictionary is broken because the class is following essential conventions that the programmer isnt.
As an aside, this phenomenon is not unique to Cocoa. I recall similar postings regarding Microsofts IUnknow COM interface in COM mailing lists. I remember postings to device driver mailing lists indicating that the poster had some very strange conceptions about what a device driver is. It seems common to me that programmers who are completely unfamiliar with graphics programming will get upset about one detail or another of a graphics API particularly when mathematics are required. My point is only that Apples Cocoa documentation and mailing lists are not the only ones to suffer from criticisms in the various categories I have described.
Back to the subject there is yet another problem: I just want to do such and such
why is it so hard? These questions often prompt the why do you want to do that? or dont fight the frameworks or what are you really trying to do? responses. I dont think any kind of documentation can avoid these questions or answer them. Sometimes the question is along the lines of I just want to build a launch vehicle that will put my neighbors dog into space. Its not as if I want the dog to survive
why is it so hard? What kind of book can really answer that kind of question?
The bottom line is that Apples conceptual documentation is very good. The only real problem is that people happen upon the conceptual documentation in random order or are too impatient to read it. The information is in there. Apples reference documentation is also quite good, but it assumes that readers are familiar with the conceptual documentation or at least the critical concepts. Apple has tried to satisfy the needs of both novices and experts and actually succeeds reasonably well in spite of the challenges.
Because Cocoa is a cohesive system that is astoundingly consistent, a programmer who groks it can correctly guess class and method names, anticipate potential error cases, avoid unnecessary code, and benefit from legendary productivity. A programmer who is missing one or more key concepts will find seeming barriers everywhere because Cocoa probably applies the concept ubiquitously.
_______________________________________________
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