Documentation Errors [Was: naming variables...]

[Richard Gaskin]

Dennis Brown wrote:
> This brings up a good point that has been bugging me for years.  It  is 
> ABSOLUTELY RIDICULOUS that the Rev documentation built in to the  IDE is 
> so full of errors.  How many repeat questions and confusion by  folks 
> trying to learn Rev are the result of wrong or missing  documentation.

I hear you loud and clear.  Back when I was learning C, starting with 
externals using Gary Bonds' "X-Command" book seemed like a good start. I 
found myself spending a lot of time double-checking everything and 
rarely got anything to actually run.  That was one of several 
experiences that made me appreciate xTalk, but a couple years ago I was 
telling that story to a good friend who's an expert in C on Mac (he's 
been known to make Apple engineers ask "How'd you do that?") and he told 
me it was too bad I let it discourage me as the problem wasn't me at all 
-- he reports that most of the C examples in that book simply don't 
work.  :(

"Missing" stuff take time to address.  I've not seen a product yet where 
people didn't complain about the docs every day until a variety of 
third-party books became available.  Don't know why that is, just 
reporting what I've seen.  It seems the only remedy is to track what's 
reported as missing and add it as soon after as possible.

But errata should of course always be a high priority.  Which erroneous 
entries have you found, and what are there Bugzilla IDs so we can draw 
attention to them?

I believe Monte does a fair job of reviewing BZ for errata reports, and 
has a track record of addressing them promptly. Getting them into your 
hands is a different matter (what should "Check for updates..." do?), 
but at least Monte does his part in a very timely manner.

> However, if RunRev would empower us, we could do great stuff about  the 
> docs.  Just from being on this list for a few weeks, I can see  the 
> quality of the user community and know that it could work -- especially 
> if it were sponsored and monitored by RunRev.
> 
> Go ahead, make my day... tell me it is already in the works  ;-)

Would "already in place" be better?  See the WebNotes feature.  It's not 
my favorite implementation of the idea, but it's a good start toward a 
mechanism for community-ehnanced docs.

--
  Richard Gaskin
  Fourth World Media Corporation
  __________________________________________________
  Rev tools and more: http://www.fourthworld.com/rev