On Dec 24, 2010, at 11:34 AM, WT wrote: > Hi Jack, > > Without getting into the merits of what expectations one should have > regarding Apple's documentation,
Or any documentation, for that matter. > I just want to point out that the documentation pages have links available > for the reader to make suggestions for improvements. If you think that > Apple's docs should be presented differently then you might want to consider > offering some suggestions directly to those who can do something about it, by > filling out the forms available through those links. Agreed -- but you might want to wait. The usually-reliable feedback form is broken, at least for me on both Safari and Chrome. I get the message "There was an error in processing the feedback you submitted." I just submitted Radar #8805484 about it. You can still submit feedback on the docs using Radar (bugreport.apple.com), which has the benefit that you'll have a ticket you can refer to. The feedback links in the documentation itself make it quick and easy to submit feedback, but communication is one-way. --Andy > > Have a good holiday. > WT > > On Dec 24, 2010, at 2:06 PM, FF wrote: > >> Thanks for reply Mr. Duncan, but it doesn't matter how you spin it. The >> title of the para. reads: >> "A complete Colored Pattern Painting Function" followed by: >> "The function incorporates all the steps discussed previously" - and this is >> what I expected. >> >> If the piece meal approach was taken to explanation, then a complete working >> example would be very helpful. >> I strongly believe that I'm not alone who finds playing with the working >> code the best, fastest and most rewarding way of learning. >> I hate as much reading instructions stretching over several pages, >> especially on the computer screen, as I hate reading ubiquitous programming >> soap-opera books, trying to teach by developing a single project over few >> hundred pages, often with missing information (D. Shaffer and few ADC books >> I own) and examples which don't work, often because the author didn't do any >> proof reading. >> >> As to the forums like this one, all questions should be answered. >> If the owner and moderators care about keeping it alive, they could appoint >> enough deputies to handle the workload. >> I'm also curious, but do not understand motivation of those who waste time >> with comments like: "it should be obvious//clear", especially if the poster >> says he's a newbie. >> This may be an instant ego massage therapy for the respondent, but for the >> poster it is unhelpful. >> My expectation was that someone would copy&paste the lines from the e-manual >> into a complete working example without error(s). >> This wouldn't take much more effort then what was written and would >> definitely earn him a big "Thank you" note. >> >> Finally, please do not construe the above as a request for such an effort. I >> printed the pages and am reading. >> >> Once again thank you and Merry Xmas. >> >> Jack. >> >> >> >> On 2010-12-23, at 6:01 PM, David Duncan wrote: >> >>> On Dec 23, 2010, at 1:09 PM, FF wrote: >>> >>>> On 2010-12-23, at 12:56 PM, David Duncan wrote: >>>> >>>>> On Dec 23, 2010, at 5:58 AM, FF wrote: >>>>> >>>>>> I copied this example from Apple docs. >>>>> >>>>> Generally the examples are there to show you how to use an API, not >>>>> necessarily to be complete standalone code. You shouldn't necessarily >>>>> expect doc examples to compile without doing extra work or cross >>>>> referencing with another example. >>>> >>>> I thought, naively, that examples and tutorials in the docs are also aimed >>>> at beginners and showing them working examples, which compile without >>>> hiccups, is the best way to speed up the learning process. >>> >>> >>> The examples are intended to demonstrate how the API works but have a >>> greater context. In particular the example you saw is but one of a few in >>> the same section describing different parts of the pattern creation. >>> Listing 6-1 and 6-2 also have critical parts of the code that you should >>> understand before being able to use listing 6-5. Because these listings are >>> shown first, it is expected that by the time you get to listing 6-5 that >>> you understand the parts that are being glazed over in that example – that >>> is, you cannot just jump to listing 6-5 and use it without having read the >>> entire section describing how patterns work. >>> >>> This isn't unlike a textbook on algorithms that expects you to have a >>> familiarity with data structures (either via earlier chapters or >>> externally) before you are able to understand how to perform operations on >>> them. >>> -- >>> David Duncan >> >> _______________________________________________ >> >> 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/jrcapab%40gmail.com >> >> This email sent to jrca...@gmail.com > > _______________________________________________ > > 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/aglee%40mac.com > > This email sent to ag...@mac.com _______________________________________________ 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 arch...@mail-archive.com
