Re: Getting Started With WO site
Re: Getting Started With WO site
- Subject: Re: Getting Started With WO site
- From: Chuck Hill <email@hidden>
- Date: Mon, 18 Jun 2007 15:32:28 -0700
On Jun 14, 2007, at 11:10 AM, Michael Warner wrote:
The amount of brain power in the WO community is staggering.
Certainly when they get ejected from The Chieftain at closing time. :-)
This was confirmed when I attended the WOWODC session last Sunday
and listened to the presenters. Yet, IMESHO, there is something
bogus about asking others to write documentation for you (see post
below). I HATE writing documentation and I am as guilty as the
next person of not doing it. Nevertheless, the difficulties in
one's initial approach to WO, Project Wonder, etc., and
difficulties in understanding and learning how to apply its (their)
most powerful features are its central weakness. And this
weakness is in turn based on a problem that is endemic to Apple and
WO -- the lack of the kind of documentation that clearly lays out
the why, when and how of the WO way.
"there is something bogus about asking others to write documentation
for you". I agree, but you are misinterpreting my point at WOWODC.
I am not asking people to create documentation for me. I am asking
them to create it for _themselves_ and others in their position.
The people who wrote the code don't need the documentation. Most
(all?) of the functionality released was not originally created for
altruistic reasons. It was created because someone who could create
it also needed it. What _they_ did not need was documentation. I
would be thrilled if everyone would provide JavaDocs, example code
and tutorials. I am not expecting this to happen. These things take
time to write well and the creators have already spent considerable
time creating and releasing their work. They have jobs to do, bills
to pay.
Clearly written expository text can make practically all of WO and
WO-related methods (including when and how to use them) accessible
to almost anyone. The elegant design aspects of WO could similarly
be revealed by way of thorough, extensive text. I argued a couple
of years ago that a multiple volume non-virtual book would be the
best way to go, because in taking on such a project, the authors
would have to develop a comprehensive sense of how all the specific
bits of information fit together. Moreover (perhaps I am too old
school) there is a public-ness and permanence (of historical value)
to a book, a concrete thing that one can point others to, as a
authoritative and centralized source. Just imagine a 2-3 volume
set sitting on the shelf of every Barnes and Noble. Most
responses to my suggestion at that time were negative, mostly
based on the idea the such a project was impractical, which it
probably is.
I suspect that it would be impractical, and it will certainly be
painful. You are looking at probably 3,000 to 3,500 hours to create
these books. Revenue at the top end will be about US$15,000. That
is around $5/hour. Do you want the job? I don't and I _like_
writing documentation.
If I wanted to wax cynical, I would say that making WO available
to a wider audience is not a good idea -- people who were not smart
enough to 'just get it' (without documentation and examples) , or
not stubborn enough to approach things through extensive trial and
error (my approach), and who were unable to appreciate its
brilliance and elegance, might start using it -- the secrets of
the inner sanctum would be revealed widely and soon all sorts of
bad things might follow.
Based on past history they would just wander into the mailing list
and start complaining. :-)
A more/less ? practical suggestion might be this -- require as part
of professional practice/protocol, that anyone who is developing
applications like WO or who is writing methods to enhance WO be
required to pair with a professional technical writer who's job it
is to writie documentation. It may well be that the developers
themselves may not be the best people to write the docs -- besides,
they won't do it anyway, as history has shown.
That does not seem very workable, given that we have very few people
contributing and fewer still documenting. If we say that anyone who
wants to contribute something is obligated to document it (or have it
documented) we can expect the amount and quality of contribution to
decrease.
I would like to see more documentation. I am writing some, I will
write more, I am helping with some other efforts. But I see a lot
more people willing to whine and ask that someone else write the
documentation than I see actually contributing something.
Chuck
On Jun 14, 2007, at 8:57 AM, Steven Mark McCraw wrote:
My understanding is that the webobjects wiki book (http://
en.wikibooks.org/wiki/Programming:WebObjects) is trying to become
the central point of documentation for WebObjects that people post
to. There's already a ton of info there, but we all know it could
use a ton more. At WOWODC, when the experts panel was asked what
could be done to help with project wonder, this is what they came
back with immediately: We need people writing documentation, and
this is the place to put it. Even if it's bad, there are so many
people watching it that bad info will get edited out quickly.
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
40global-village.net
This email sent to email@hidden
--
Practical WebObjects - for developers who want to increase their
overall knowledge of WebObjects or who are trying to solve specific
problems.
http://www.global-village.net/products/practical_webobjects
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden