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
_______________________________________________
use-revolution mailing list
[email protected]
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
