On May 23, 2006, at 1:05 AM, Anjo Krank wrote:
Am 23.05.2006 um 08:25 schrieb Mike Schrag:
I put up some initial docs on the components available in Wonder's
Ajax framework to try to address some of the "documentation gap".
Brrr. What a pompous asshole... I thought about writing something
re his "myth" stuff, but why bother.
Obviously this mail wasn't meant to be sent to two mailing lists.
I apologize for that, but I'm really short fused when I hear this
"Wonder has no docs" crap over and over and over again.
Well, I'll let it go this time, but I'm pretty furious about being
insulted in public, not to mention having personal information spread
across the list. I'm under a lot of stress right now, I didn't need
more. If you have a problem with me in the future, talk to me, not
the mailing list. Email is an imperfect medium; always assume that
how you took something may not be how it was meant. In return, I'd
like you to grant me a moment of your time, and listen with an open
heart.
In this case, I don't think I said "no docs" I said there was a gap
and I wasn't just talking about Wonder, I was talking about WO in
general. I'll probably keep bitching about the WO documentation until
there's a book at least as good as the Rails book on WebObjects. The
newbies need a step by step guide that points them towards D2W and
Direct Actions and away from component actions. Even Apple isn't
immune, look at store.apple.com or jobs.apple.com.
As far as Wonder goes, I was only referring to the new Ajax
Framework of Mike, and it looks like he's doing a great job of
addressing it. Good enough in fact, that I'm going to approach him
about working together on the Ajax framework instead of rolling my
own and having to reconcile them later. I think I'll even contribute
to his docs.
But obviously there is a gap, or people wouldn't keep saying "no
docs". If one person says "you have a big nose", they're a pompous
asshole. If two people say "you have a big nose", they're probably
still pompous assholes, but you probably have a big nose. (Note: I
have no idea what Anjo looks like.) Even open source/free projects
needs to listen to their customers, and in this case, the customers
are saying "we'd like more docs".
Now at least part of the problem is that someone new to Wonder is
pointed at wonder.sf.net, and sort of left there. Wonder does have
"javadoc" documentation that I've been able to find, and I've seen
short articles here and there about Wonder, but if you go to
wonder.sf.net, there is no tab that says "documentation". I think I
found the javadoc documentation by accident via google, later on I
found a link in the "news section".
And personally, I think this trend of lazy programmers to just
throw together some javadoc documentation and consider themselves
done isn't that great. (You'd think they'd at least run doxygen to
get slightly better looking docs.) Wonder has gotten fairly big, and
now has numerous libraries, some of which are orthogonal to each
other. But god knows what exactly you need to install if you want one
feature over another... (unless you read the top level README.txt
file, but then you've downloaded everything...)
So Anjo, if you're tired of hearing no docs "crap":
1. Make a web page that links to all the existing Wonder articles
and such from sf.net to stepwise or wherever. Put THAT on the getting
started page. In general, ask yourself: What can I find out about
Wonder from wonder.sf.net? What can I find from Google? Why isn't
that the same set of information.
2. Try doxygen instead of javadoc, and put the link up on the
main sf site. Reading javadoc makes my eyes bleed.
3. Pull some of the contents from the various README files into
web pages on sf.net. Start with the very top README.txt file, there's
no reason why someone should have to download the whole set of source
code to find out what's in "Adaptors".
4. Break the Orthogonal components into separate downloads so
newbies can ease into Wonder.
I think at least some of the complaints would go away at that point.
Pierce
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list (Webobjects-dev@lists.apple.com)
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/webobjects-dev/archive%40mail-archive.com
This email sent to archive@mail-archive.com
