Rant Re Rev Documentation

[Timothy Miller]

>Timothy Miller wrote:
>>Howdy, y'all,
>>
>--- snip ---
>>
>>As usual, I searched the docs, but couldn't find anything. If the 
>>information is in there, it's hard to find.
>
>
>I suspect this happens often. For this reason, I sometimes wish 
>there were a Rev feature we could turn on which would collect our 
>failed Docs search phrases, give us space to explain in longhand 
>what we're looking for, and send the phrase and the explanation to 
>RunRev. The purpose of the feature would be to inform those who 
>create the docs of the language we use when searching, so maybe the 
>docs could be brought more in line with our way of looking for info.
>
>Food for thought.
>Phil Davis


Hi Phil,

I appreciate your comment. It's a good idea. However, I'm not sure 
that the elementary information I needed exists in the onboard Rev 
documentation. Well... Pieces of it are in there, no doubt, but maybe 
not in a form that would have been useful to me, when I was stuck, 
given my skill level, which is above newbie, above novice, maybe 
around amateur, or a bit lower.

All I needed was a tip from the list. Simple was good. Jacque has a 
gift for getting the gist of a question, and then answering it 
clearly and briefly. (I appreciated the other suggestions also, 
though they were more complex than I really needed.) I enjoyed a 
blinding flash of the obvious, and I was ready to do my work.

I fear your comment is more than food for thought. It seems to me, 
sometimes, that your comment represents a life or death issue for 
Revolution. Rev is supposed to be "enterprise-ware" if I'm not 
mistaken. If I understand the term, enterprise-ware is appropriate 
for do-it-yourself end users.

In my opinion, it ain't enterprise-ware. Not yet, anyway. A person 
with my skill level as an all-around computer user, for many, many 
years, and former heavy HC user, should suffer far less difficulty 
with Rev than I have experienced. And I've been spending money on an 
(excellent) consultant, too. Consider the number of professional 
developers -- and other experts -- on the list, versus the number of 
newbies-with-questions. Look at the number of do-it-yourself end 
users, who use Rev for serious business. (Sometimes, it seems like 
I'm the only one in the world.) That suggests to me that something is 
wrong. (I assume it's obvious that the experts predominate.)

There have been a couple of bugs, and of course Rev is more 
feature-rich than HC, and it's different from HC in some important 
ways. But these have not been the main obstacles for me. The main 
obstacle is that there is no adequate documentation for Revolution. 
There's not even a manual! Even HC 1.0 shipped with a pretty good 
manual! And a reference guide, too, as I recall. Danny Goodman's HC 
books appeared not long after. They constituted more-than-adequate 
documentation, and they set the standard that Rev must follow, one 
way or another, and soon!

(I found a comprehensive Trancript dictionary on the Web the other 
day. It was over my head. That's not the answer. I'm not even sure I 
understood what it was.)

Rev's onboard documentation is a very good start, and I love it 
because it's onboard, and free. But many dictionary entries are just 
too terse. Terse is what I want -- sometimes. Like if I've forgotten 
some detail I used to know. At other times, like when I'm trying to 
do something I never did before, or I can't get something to work and 
I can't figure out why it's not working, I need verbose. A book could 
do that, but this is the kind of situation that is best handled by 
hypertext. (Given Rev's hypertext capabilities, that's ironic at the 
laugh-or-cry level.) In other words, the onboard documentation might 
be the best delivery method. Rev will certainly be able to attract 
customers more effectively, if the customers can get started without 
buying an expensive and intimidating thick book.

Getting back to terse and verbose, if I filter or search the 
dictionary, it seems to me I should get the terse explanation. A 
simple link could, and should, give me a more detailed and digestible 
verbose explanation.

The related terms are great, sometimes. If they're mostly mysterious 
to me, they are too terse, also. A verbose version of related terms 
would provide a fairly brief and digestible summary each term's 
meaning, with a link for each one, of course.

Scripting examples in the onboard docs are very sparse. Often there 
are about three. Once again, sometimes that's fine, sometimes not. If 
none of the examples are particularly relevant to what I'm trying to 
do, or fix, I've got a problem. I should have the option of a verbose 
version of the scripting examples. Rev is so feature-rich that two or 
three dozen scripting examples would be barely sufficient, in some 
cases.

The onboard docs are missing other obvious links, as well. How about 
a "gotchas" link for most dictionary terms? The gotchas could be 
rank-ordered from mistakes commonly made by newbies to mistakes 
commonly made by experts. Sort of like the list of commonly 
misspelled words found in some dictionaries. (Funny... I'm not sure 
how to spell "misspell.")

If the onboard docs could reach the foregoing specifications, and 
soon, they'd be good-enough. For instance, the verbose explanation of 
the drawing tools or images or backgrounds -- or something -- would 
have told me how to do what I wanted to do (I'm talking about my 
previous query to the list). I would have found it quick enough.

Beyond "good-enough," a few more links under most dictionary terms 
would raise the level of the onboard documentation from good-enough 
to excellent. For instance, how about a "clever scripting tricks you 
probably wouldn't think of yourself" link? Or a "for experts only" 
link?

Maybe someday, many dictionary terms could be linked with mini-stacks 
that actually demonstrate the use of the command, property, function, 
object or whatever described in the documentation. These could be 
downloaded by the user at need, or downloaded all in an archive, for 
local retrieval by the documentation stack, as needed. (I assume the 
onboard documentation is a stack.) The mini-stacks could be donated 
by Rev-loyal users.

Your suggestion is also excellent, and could also greatly improve the 
onboard docs, by adding some intelligent searching to the abysmally 
simple filter and search functions currently available. If google can 
ask, in a few nanoseconds: "Did you mean to search for podophilia 
rather than pedophilia?" I guess Rev's docs could give us a link 
like, "Click here for more ideas if you didn't find what you need to 
know." Boolean searchability of the documentation, including "near" 
and "not" and field restrictions, and such, could be a big step 
forward, too.

I just can't understand why Rev hasn't done all of these things 
already. It might be a somewhat daunting task, but it's minuscule 
compared to the trouble it took to build Rev in the first place. If 
it's too much for Rev's overworked staff, they could get 95% of the 
work done for free. All of the items I've mentioned could be 
submitted by users to a wiki. Of course, Rev would need editorial 
control of the wiki to keep out errors and vandalism. Even the 
editorial control of the wiki could be delegated to experienced and 
responsible volunteer users, who could check each other's work, and 
so on. Professional developers could be allowed to place 
self-promotional links in their wiki contributions.

Sure, Rev is a privately owned, for-profit company. I don't' care. 
It's in my interest for Rev to succeed as a commercial product. The 
price is quite reasonable anyway. Maybe someday there will be a free 
opensourced version of Rev. Or maybe not. I don't care.

Ironically, Rev is also probably the ideal application for building a 
wiki. If Rev is in a hurry to start a wiki, I understand free, 
off-the-shelf wiki software, is readily available.

As the  documentation stack grew and improved, Rev could arrange, in 
a forthcoming upgrade, a convenient way for users to check for the 
latest version of the documentation stack, and download as needed.

When I rant like this, I always worry I will appear not to appreciate 
or respect Dan Shafer and his books. I do, and I do.I own volume 1, 
and consult it often, and I recommend it to others. I don't know 
about Volumes 2 and 3  -- haven't tried them yet. I understand they 
are not yet published, But Dan's books are very different from Danny 
Goodman's HC handbooks. It is true that Goodman walked HC 
kindergartners through the creation of simple and then increasingly 
complex stacks. But the HC Handbooks did far more than that. When I 
was teaching myself HC, I had the keyboard in one hand and Goodman's 
book in the other. I started with "new stack." I asked questions on 
the HC list from time to time, but the vast majority of the time, I 
found what I needed to know easily enough in Goodman's guides. I 
depend far more heavily on this list than I ever did on the HC list. 
And Goodman had the disadvantage of working with ink on paper. If a 
guide like that could be continuously improved, expanded, indexed and 
error-corrected, because it was a free downloadable, wiki-enabled 
stack, imagine what it could be!

Getting back to Dan -- I sometimes wonder why Dan didn't start by 
writing a comprehensive reference. As I think about it, that's 
probably a no-win proposition for an author, because Rev's free 
onboard documentation would be a hard act to follow, even if it's not 
that good. And as soon as Rev improved its onboard documentation, the 
book would stop selling. I'd guess that's Dan's reasoning, but it's 
only a guess.

Rant concluded. Maybe it's been said before. It probably bears 
repeating anyway.


Tim Miller