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 _______________________________________________ use-revolution mailing list [email protected] http://lists.runrev.com/mailman/listinfo/use-revolution
