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 ___________________________________________________________ [EMAIL PROTECTED] http://www.FourthWorld.com Tel: 323-225-3717 AIM: FourthWorldInc _______________________________________________ use-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/use-revolution
