• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag
 

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Re: Getting Started With WO site
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


References: 
 >Getting Started With WO site (From: David LeBer <email@hidden>)
 >Re: Getting Started With WO site (From: Janine Sisk <email@hidden>)
 >Re: Getting Started With WO site (From: Steven Mark McCraw <email@hidden>)
 >Re: Getting Started With WO site (From: Michael Warner <email@hidden>)

  • Prev by Date: Re: irc channel
  • Next by Date: Re: Getting Started With WO site
  • Previous by thread: Re: Getting Started With WO site
  • Next by thread: Re: Getting Started With WO site
  • Index(es):
    • Date
    • Thread