[albatross-users] Comments on using examples...

[Sheila King]

--On Thursday, July 03, 2003 1:50 PM +1000 Cameron Blackwood 
<korg at darkqueen.org> wrote:

> I dont know about other people, but when I see an example in docs, I
> often like to actually:
>    1)  try it myself
>    2)  modify it
>    3)  use it as a base for what I really want to do

Agree.

> Eg:
> www.object-craft.com.au/projects/albatross/albatross/tag-comment.html
>
>       trying it:
>         Hands up anyone who has used albatross in interactive mode?

Yes, I have. For testing/learning only, of course.

I primarily used it that way because of two reasons:
(1) the thing I was trying to learn/master was shown with examples in 
interactive-mode in the documentation.
(2) it was quicker to do that then modify the app I'm working on for test 
purposes.

>         Interactive python dumps are not much use because:
>            1) noone would ever do that

I assume that you mean here, that no one would use Albatross in production 
in such a manner? However, interactive is mostly used (by developers) for 
testing purposes, even when not working with Albatross. At least, that is 
my take on the matter (as a clearly peon developer type).

>            2) you cant cut & paste to test (well you can, but you have
>               to cut and paste specific bits (not the output) and you
>               cant cut and paste the multi-line examples, thanks to the
>               pythonic '... '/'>>> ', without having to be _VERY_ careful
>               about indenting.)

Agree that c&p is much more difficult/annoying from the interactive 
examples.

>            3) if I find what I need, then I need to translate it into a
>               SimpleApp (or whatever) to actually use it (Thus, shouldn't
> it                be a SimpleApp example to start with?)

For what it is worth...

I also found the amount of interactive examples in the documentation to be 
... uh ... not what I would have preferred to see. Some of it is good, or I 
might not have even realized how to run Albatross interactively (or even 
thought of it as being possible). I do think some examples of running it 
interactively are good, in order to make this point. Perhaps put it into a 
small section of the documentation, as it's own topic: "Running Albatross 
in Python Interactive Mode" and then a few examples showing how to do that. 
And then convert the rest of the interactive examples in the documentation 
to downloadable/runable files.

BTW, something I never mentioned but that bugged me in the docs:

The use of the '<magic>' context in the interactive examples. Bugged the 
crud out of me as to what it was, why it was named that way, why it worked. 
Eventually just accepted it as black magic and moved on, but wasn't really 
happy with having to do that.

The examples being currently uploaded to the Wiki may make up for the 
"short coming" of having so many of the documentation's examples shown as 
interactive mode.

I also want to re-iterate that I find the Albatross product (and its docs) 
to be first rate, and only make negative comments at all in the hope of 
offering feedback for improvement of an already fine project.

-- 
Sheila King
http://www.thinkspot.net/sheila/
http://www.k12groups.org