Your documentation isn’t the worst that I’ve seen, but I’ve easily seen better! There needs to be more examples and things need to be easier to find. I finally got smart and bookmarked the page about conditional statements the 3rd time I spent 10 minutes looking for it. Another example is the ‘Ad Hoc Do Box’. It took me quite some time to find the sparse documentation about that for two reasons: 1) In every other program I have ever used it is called an Immediate Window, 2) Every picture I saw of the Run Window didn’t even mention it. Then the paragraph on the AHDB said you could display variables, but it didn’t say how. It took me a good five minutes to dredge the word ‘show’ out of my brain.
Thanks for the feedback. I agree that more examples would be helpful. For finding things, we recommend opening the documentation in Apple’s Preview application (this should happen by default), and typing in the search field (choose Find… from the Edit menu if it’s not showing). This search capability is good, but of course you’ll need to know what word to look for, which isn’t always obvious especially when you’re just learning the program.
The Ad Hoc Do Box is explained on p. 83-84 of the Eggplant Reference manual (version 3.0), as part of the description of the Run window’s features following the picture of the Run window on p. 81. Was it a different picture of the Run window that you were looking at? I’m afraid I’ve never heard the term “Immediate Window” before, but will keep that in mind (perhaps we can work it into the documentation somehow for the sake of people searching for that term).
To display the contents of a variable, the word you want is “put”, not “show” (if you’re very observant you may notice some put commands in the picture of the Run window, but I think adding an example or two as you suggest may be a good idea).
The problem with searching that way, which is what I have been doing, is that if you don’t know exactly what you are searching for, you get way too many false positives. For instance, I didn’t remember the section was called ‘Conditional Statements’, so I tried searching for ‘if’, ‘then’, ‘else’ and getting a slew of hits. Having an index at the back of the document would be really useful.
It’s called the Immediate Window in most Windows based IDE’s. And while Eggplant isn’t (yet) in the same category as an IDE, since it has a debugger I’m comparing it to an IDE.
Ok, I’ll bite. What’s wrong with ‘show’? It does displays the variable (and admittedly the date and the command which I don’t really need).
The ‘show’ and ‘hide’ commands are used to display (or hide) the Remote Screen window or the Run window during a script run. As it happens, they also log the value that was specified (as a side-effect, really, which happens to be useful to you). Using ‘show’ to display values, if the value of your variable happens to be “run” or “remote” you’ll get what (to you) are some interesting side-effects. 
Well, so long as they are interesting. I have no tolerance for boring side effects. 