Re: Cocoa et al as HCI usability problem

FROM : Scott Ellsworth
DATE : Wed May 21 22:18:31 2008

On Wed, May 21, 2008 at 12:14 PM, Jeff LaMarche <<email_removed>> wrote:
>
> On May 21, 2008, at 1:30 PM, Peter Duniho wrote:
>

>> My _main_ objection is how newcomers to Mac development are treated.
>>  Please, when someone new to the current Mac development environment brings
>> up one or more of these points, don't say "well, you're too inexperienced to
>> see why [Obj-C|Cocoa|the documentation|the tools] is/are so great".  Don't
>> say "you're riff-raff, it's supposed to be hard, we _like_ that it's keeping
>> you out".  Don't say "you must not have read the conceptual guides,
>> otherwise all this would be clear".  Or any of the other condescending,
>> presumptuous things that I've seen said on a semi-regular basis

>
> Okay, first, Scott, my apologies - I'm letting the thread die after this --
> promise -- but needed to respond to this one tiny point.
>
> Pete - you complain that people should treat newcomers better, yet here you
> are characterizing what many of us have said in a blatantly antagonistic
> way. Riff-raff? We "like" that it's keeping you out? Nobody said any such
> thing. It may be that people won't want to help you now, but not because
> you're a newcomer, but rather because you're baiting people and unfairly
> characterizing our words and our intentions. Don't ascribe ill-will to
> people who tell you things you don't agree with or don't accept as true. I
> guarantee you that every response was an honest attempt to help.


Thank you, Jeff.

You phrased this much better, and in a much more constructive way than
my own initial response.

Let me emphasize one more piece of constructive advice - if you do not
like the docs and examples, file bugs on each and every page that
specifically failed you, with real details.  I heard at least one
respondent state that they were too busy to list any explicit examples
of doc failures, but that they saw lots.  Not filing the bugs that
annoyed you is bowing out of the only process that can correct the
official docs.

The docs are far from perfect for all comers, and the authors have no
way of knowing how they failed you, and why you thought any specific
page was the right place to look.

Web Objects tutorials, at least when I went through them last, tend to
have a robocode section, followed by an explanation.  Without fail,
the people I have guided through them stalled when they hit something
they did not understand, rather than reading a few paragraphs forwards
for a definition.  Just a short note that 'foo, bar, and the baz
method are defined after the example' would have helped.  And yes, I
commented on those pages when I last went through them.

File an issue, and state as clearly as you can how you got the page in
question, why you thought it would help, and exactly how it did not.
You may not be able to say what the content should have been, but if
the docs folks know that you honestly expected a discussion on Garbage
Collection in the NSArray docs, they can at least consider linking to
the conceptual guide with a message whose text would have gotten your
interest.

Scott