Documentation Errors [Was: naming variables...]

[Dennis Brown]

On May 6, 2005, at 11:44 AM, Richard Gaskin wrote:

> 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.

This mail list is addressing missing stuff every day.  Unfortunately,  
in a couple of weeks I have seen the same stuff rehashed already.   
That must be because it is not obvious to the newbe how to find the  
info he needs.  Being able to capture the valuable info on this list,  
without having to go through the painful task of searching for a term  
and wading through all the discussion to find the nugget in the  
archives would be ideal.  It has the making of a great tutor.

>
> 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?

#2778 #2753 are the ones I entered.  However, I found so many minor  
issues with the docs that I just gave up on trying to report them.   
Seeing the priority given to these issues, and the amount of time I  
would invest in documenting the errors, it just did not seem to be a  
productive use of my time.  With the web notes, I will reconsider.   
It would be nice to be able to ask a question about the missing or  
wrong info in the web notes, and have someone respond right in the  
note with the corrected or expanded info.  I was encouraged by  
Kevin's chat today when he mentioned addressing the BZ issues and  
response delays.

>
> 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.

I did not realize that notes I put there would be visible by  
everyone.  Ok I just put in the note on the numbered variables.   
However, I would have preferred to have it done in such a way that  
others would look at what I added and make sure my fix is right  
before someone else is led astray.  Does anyone get notified when a  
note goes in, to check that it is not spam or worse.  Because this  
doc issue has come up before, why did nobody else put a note in?   
Isn't anyone using this feature? A search on "web notes" in the ref  
doc did not produce any hits.  This feature could be made to work  
with a few tweaks --like update and downloading notes to local, or a  
flag that says a note is available for this topic.  How about new  
topics that can be added to the doc also.  This could work much  
better than BZ for noting the errors, adding missing content and  
examples --if it were made into the standard method for addressing  
these issues by RunRev.

Dennis