From: ben syverson <[EMAIL PROTECTED]>
This is going to sound bitchy, but it's hard for me to have any
sympathy for vague complaints about the docs or the usability of
Cocoa.
That does sound bitchy. I mean, it's fair enough to say that people
ought to be providing specific feedback and constructive complaints.
But to have _no_ sympathy? That's harsh.
Real people are having real problems getting into Cocoa. I don't see
the kind of repeated commentary about poor documentation and
difficult APIs in the C#/.NET forums or Java forums. It comes up
once in a blue moon, but not with the reliability I've seen here, nor
is there nearly the kind of practiced, organized defense seen here
(which again suggests a certain regularity to the complaints).
I had a big long reply (even longer than this one :) ) written to
Julius's initial post under this subject and detailing many of my
concerns and complaints about Objective-C, Cocoa, and the
documentation, but decided the better of posting it. However, I'll
say this: I agree that at least for me, the fundamental issue is that
from a "usability" point of view, Objective-C, Cocoa, and the
associated documentation leave something to be desired. I found
Julius's comments regarding "usability" to be right on the mark, at
least in the general sense.
There's no question in my mind that Cocoa is a nice framework, and
that the entire environment provides some good productivity-enhancing
features. But it's also clear that those benefits are only really
available to someone who has already invested a lot of effort in
learning it. The "rule of least surprise" doesn't apply; maybe it
does to the framework, but not to the documentation and definitely
not to the tools.
I contrast that with my experiences moving to C#/.NET and Java from
the Win32 C++ world. Now, at least with .NET it is true that to some
extent, I benefitted from having a fair amount of Win32 expertise.
Some of the paradigms map closely, and that helped. But there's a
lot in .NET that is entirely new, and that was easy and fun too. And
Java was completely foreign to me when I started using it. In
neither case did I find myself feeling like I'd just entered a whole
new world where, until you had gone through the entire hazing
process, one could never really be effective as a programmer.
.NET and Java were _fun_. They are still fun. I love writing code
for either platform. I ported one simple .NET application to Cocoa
and haven't had any interest in writing any more Cocoa code at all.
I'd love to see the Mac succeed as a platform. But frankly, I think
you already have to be a pretty hard-core Mac fan, and _really_ want
to see your software on the Mac, to be motivated to spend a lot of
time with Cocoa. Until programming in Cocoa is fun for _everyone_,
not just the few who have made it through the gauntlet, I don't see
it attracting a large following.
Those who love the Mac, and who love Cocoa, ignore this kind of
feedback, provided to them on a regular basis, at their peril.
[...] But I can't think of a single time when I've been unable to
figure out
where to look for guidance on a problem, or have been unable to
interpret that guidance.
For what it's worth, it's not (to me) a matter of not being able to
figure it out at all. It's how much effort is required to figure it
out.
MSDN is sprinkled with code samples. Everywhere. Granted, some of
them are kind of silly, and some of them are just plain wrong. But
on the whole, they are pretty good. More to the point, they exist
for pretty much _every_ documented API element. Class methods,
properties, events, fields. All have a dedicated doc page that
includes some sample code (in many cases, a single sample is shared
among multiple elements...but that's just efficient doc writing).
Contrast to the Cocoa docs, where a single class is documented in
just one web page, with practically no sample code at all and
incredibly brief descriptions of each element.
Oddly enough, the same complaint can be made for Sun's docs for Java,
but I haven't found that to be nearly as great a degree of a problem
there. It's hard for me to put my finger on exactly what the
difference is, but I'd guess that at least partly it has to do with
the fact that Sun's docs include frames with navigation panes that
help orient you within the API, so that as you jump around you have
some idea of what classes are related to what and why. The Java
tutorials also seem more to the point.
I know that given time, I can figure pretty much anything out. But
in the Cocoa docs and API, it can sometimes be a real chore.
As an example, I found myself wanting to exclude an area from my
clipping region. Nothing complicated: I had a rectangular area, and
I wanted to draw everywhere _except_ a specific sub-rectangle. The
docs were quite prideful as to how, since Cocoa clipping uses the
NSBezierPath, you have practically infinite control over clipped. No
doubt this boasting was reasonably accurate (*). And yet, even as it
hints tantalizingly at the idea that there's a way to do this (see
"Modifying the Current Graphics State"), it doesn't quite get you there.
(*) And that's another thing...nowhere else have
I seen documentation that wastes so much time
explaining why _their_ API and paradigm is superior.
Why all the proselytizing? Just tell me how to get
the damn job done! I get it...Apple thinks that
there's no better way to write software than using
Cocoa. Stop hitting me over the head about it!
I was finally able to, after reading documentation in three different
places that discuss NSBezierPath, connect the dots so to speak and
figure out how the heck to get NSBezierPath to do what the docs
hinted it could do.
For that matter, why is the entire NSBezierPath API based on
"append"? Why isn't there just a "remove" semantic too, that
internally translates to the appropriate "append" behavior?
It's not that it's not possible to do what I wanted to do, or even
that Cocoa is lacking in functionality (at least in that area), or
even that the docs fail to include enough information to figure it
out. It's just that the docs seem to spend a lot of time discussing
either incredibly basic things, or incredibly complex things, and
failing to cover some of the more typical use cases.
So often when reading the MSDN docs and Sun's tutorials, I find code
samples and use explanations that are pretty close to what I'm trying
to do. Reading the Cocoa docs, as a person not writing really
complex programs, I find myself thinking "well, that's
interesting...but what about the kinds of things the other 98% of the
programming world wants to do?"
And to barely touch on another point of dissatisfaction, I'll point
out that least in Xcode 2.4, I found the Help topics for IB to be
fairly useless, as they appeared to be written for a previous version
of IB and often described things that were simply not even present in
the version I was using. A similar issue came up when I tried to use
Apple's docs to learn how to add my own Help for my program, only to
discover that the tool it referred to had nothing to do with the tool
currently in use.
Finally, the Cocoa fanatics would do well to not only recognize that
these dissatisfactions with the environment are not limited to just a
handful of malcontents (if you think you spend an inordinate amount
of time addressing these complaints now, just wait until if and when
the Mac is actually a popular programming platform), but to recognize
that individual complaints are somewhat varied.
For example, while I tend to agree with the issues raised about the
documentation, it doesn't bother me nearly as much as some of the
fundamental issues around Objective-C. Having spent so much time
using languages like C++, and later C# and Java, I get annoyed when
the language tells me that I need to start dealing with OOP concepts
such as object construction manually. Especially when this means
that in spite of the language encouraging me to write an appropriate
"init" method (the closest thing to a constructor Obj-C seems to
have), it turns out that for my sub-classes instantiated by IB,
that's never actually called. Duh.
I also find the dynamic nature of the language to be a liability, not
a feature. I keep hearing people say "sure, the compiler can't tell
you that method call is incorrect, but that's the cost of having such
a dynamic language", but then when pressed they are unable to
describe why that dynanism is beneficial. The vast majority of
software is easily written without that sort of capability, and with
much stronger compiler support for code correctness.
I realize there are plenty of people who love Obj-C. Heck, I'd guess
that most of the people reading this email love it. But you have to
understand that you're a fairly homogenous, isolated audience.
And as long as you guys keep insisting that there's nothing wrong
with the environment, and that people "just need to get used to it"
and "then they'll love it", you're not going to get the kind of
developer excitement needed to ensure the kind of developer support
required to get the Mac really into the mainstream. At a minimum,
market growth is going to happen a LOT more slowly than it could
otherwise.
And yes, it's fair to ask for specific, actionable criticism that can
be used to improve the documentation. But the fact is, when you're
knee-deep in trying to decipher the documentation and the API, it's
hard to remember to take the kind of notes that would be useful in
reconstructing the difficulties encountered. By the time I got my
little Cocoa program working, I was just so happy to finally be done
with it, the last thing I wanted to do was spend a bunch of time
trying to remember what was so painful about it and submitting all of
that information to Apple.
Yes, I agree it would have been better for me to do that. But I've
got other things to do, and frankly given the utter lack of sympathy
I found in the Mac development community for the issues I was going
through, I didn't find myself very motivated to spend my own time
trying to improve things. If Apple and the existing dev community
doesn't care, why should I?
Phew. I got rid of one long reply, only to eventually write
another. I guess I really needed to get that off my chest. Suffice
to say, I have not found the experience of writing Mac software
nearly as pleasurable as writing .NET or Java software. It's only
marginally better than the experience of writing to more primitive
platforms, and that's only because the Cocoa framework itself
counterbalances the awkward aspects of the rest of the environment.
As long as the existing Mac dev community, and especially Apple's own
developer support staff, fails to understand this, the Mac just isn't
going to attract people to write code just for the sake of writing
code. And people writing code just for the sake of writing code is
one of the biggest ways a platform gains strong developer support.
Pete
_______________________________________________
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]
