standalone has plainly readable transcript

[Richard Gaskin]

Victor Eijkhout wrote:

>> I should have made the connection
> 
> Any time you say that, it really indicates a deficiency in the
> manual. As a manual writer myself, I don't approve of the "you can't
> say it wasn't there" style of technical writing.

Fortunately that doesn't seem to be the style Jeanne employs in documenting
Rev.

"Any time" may be a difficult position to support given the variety of posts
here about the more-extensive-than-Macromedia's documentation, some
evidencing a greater earnestness in trying than others.

As a documentation professional, surely you recognize the dynamic that
occurs once the meme of "the docs are inadequate" grows legs: an element of
"learned helplesness" creeps into the community, in which newcomers read
posts slamming the docs and begin to assume they needn't even try looking.

While specific constructive suggestions sent to Jeanne are invaluable in
providing guidance for further expansion, posts making broad negative
generalizations about the docs can be a disservice to the readers here,
misleading them to believe that finding the answers they need may be harder
than is actually the case.

This latest issue of password-protecting stacks is a good case in point. If
something seems obvious enough to get alarmed over, it may be obvious to the
RunRev team as well, and might well have already been addressed.  The same
amount of effort as required to post an alarming note to the list is all
that's required to recognize that in this case such a post isn't necessary:
Step 3 of 3 in the Distribution Builder has a field clearly labeled "Encrypt
with password" in the middle of the card.

And in the last several weeks a lot of posts have been searching for
language features in which what was being sought is the actual keyword they
were looking for; submitting the same term to the Transcript Dictionary as
was submitted to the list would have yielded immediate gratification.
Sometimes the problem is believing things can be as easy as they are. ;)

>From time to time we all overlook the obvious and lord knows how many times
I've done so myself, as I did just last week with the diskspace function.
There is no shame in that, it's just part of being human; we just get the
answer and move on, and it probably helps other readers along the way.  No
big deal.

But to extrapolate that overlooking something obvious always means that
there's something critically wrong with the UI or its documentation is not
likely to hold up in some cases, and in such cases slows the learning
process for others unnecessarily.

We're not talking about cooking, which my failed attempts suggest is hard
enough to learn (for at least this bachelor).  Developing software is an
inherently complex task, and while Rev is arguably among the easiest ways to
accomplish as much as it lets you do, there's only so much it can do to
simplify the process.  A 1000+ token interpreter like Rev's is a complex
system, integrating with even more complex systems like QT, database
engines, and 12 different operating systems.  While imperfect, Rev makes the
software process orders of magnitude more efficient and easier than
traditional methods like C++ or even Pascal (in some cases yielding superior
results), and is far simpler to learn than the world's most popular
scripting language, JavaScript.  And at version 2.0 it's still quite young,
with many areas in which it can learn and grow to make that process ever
simpler.

There are areas where Rev could better exploit the principle of progressive
disclosure (a long rant about the evils of Photoshop's UI on the evolution
of software design is growing increasingly hard to resist), but as a whole
it's not bad and specific suggestions for improvement seem to be heard.

A post on general tips for learning Rev is in the works, but I have a
problem with brevity (or more specifically a lack thereof <g>), so I'll
leave that out of this post and just close with this sincere question:

As with any software package in earnest development, continual improvement
seems a well demonstrated goal of Jeanne and the rest of the team, as with
the inclusion of the universal Help search plug-in added in v2.0.1 by
popular request.  Given your experience, what specific remedies would you
recommend? 

-- 
 Richard Gaskin 
 Fourth World Media Corporation
 Developer of WebMerge 2.2: Publish any database on any site
 ___________________________________________________________
 Ambassador at FourthWorld.com       http://www.FourthWorld.com
 Tel: 323-225-3717                       AIM: FourthWorldInc