[pmwiki-devel] ZAP cookbook, www.zapsite.org

[Crisses]

On Dec 7, 2006, at 3:54 AM, Christophe David wrote:

> I am still trying to encourage friends to have a look at the ZAP  
> features on www.zapsite.org.

I'm currently trying to follow one of the snippets and get it to work  
by adding information to a different group.  The documentation is  
lacking.

It's my belief that tutorials are for hand-holding and explaining you  
why you are doing something.  You learn from a tutorial because it  
teaches you the logic and reason behind coding choices.  There's one  
tutorial that is only a walk-through, not a teaching instrument.  Not  
everyone has the "teacher gene" so I'm hoping to help out there --  
I'd like to think I have that gene so let me prove it ;)  Jiri did a  
good job creating and documenting a forum, and I can't wait to give  
it a try!!  But changing things from where Jiri started will be  
harder, because I'd be playing monkey-see, monkey-do with my current  
knowledge of ZAP -- a straight cut & paste job.  Right now I change  
things and they just break.

example:
http://www.fast.st/zap/pmwiki.php?n=Docs.DataPage
it says the directive is:

(:input type datapage* "<Group>.<Name>":)

but Jiri's forum has it without the asterisk after datapage.

Neither the ZAP documentation nor Jiri's tutorial tell me anything  
about this directive that I find extensible.  The documentation page  
doesn't explain the * -- and Jiri doesn't say why it's not there.   
The documentation doesn't give examples of this from real use.

When I do finally understand, I hope I can help improve the  
documentation.

> Unfortunately, despite the obviously considerable time spent on  
> improving the documentation and giving support, there are still a  
> few things that can discourage even the most motivated visitors :
>
> Examples:
>
>     - when visiting www.zapsite.org, you cannot even read the  
> documentation without being logged on.  The new visitor has no clue  
> as why "nothing works" without spending a lot of time searching.   
> Why not have full free access to everything except the parts that  
> actually use the ZAP features that require to be logged on ?  Why  
> not "pre-fill" the username/password fields with "Guest" and "test" ?

This field IS prepopulated for me.  Maybe I pre-filled it at some  
point and my browser remembers it?  I thought the first time I tried  
that it was already done for me.

>     - even more disturbing : when visiting ww.zapsite.org with  
> Windows / Internet Explorer using default security settings, many  
> users can simply not log in at all: the cookies are blocked because  
> they are set for www.fast.st and not www.zapsite.org.  Users must  
> click on an icon in the status bar to see the security warning, and  
> then find out that they could be more lucky with http://www.fast.st/ 
> zap/pmwiki.php ...

I personally don't like the iframes because I can't open multiple  
tabs, so I open the frame in a new window and deal directly with  
fast.st -- then I can open a zillion windows, bookmark pages, look  
through my history etc.

I suggest sending your friends the direct link to fast.st :)  It  
looks the same.  You might even make a note in the comments on the  
PmWiki ZAP recipe page about it.

>     - then when they finally managed to sign in and have found out  
> that ZAP provides interesting markup to make forms, they cannot  
> find out what the syntax is.

Most snippets have a view source link on them, and there's a view  
source link on the site pages anyway.  Is that working for you?

>     - the "documentation" section should probably be renamed into  
> "reference", and should be more comprehensive, with  exhaustive  
> lists of all parameters and their meaning, and pointers to the  
> relevant snippets.

I am finding it frustrating that only parts are documented at all,  
and that there aren't sufficient examples for me to "get it" and be  
able to extrapolate new uses from the directives.

Then again, I just started trying to read through the documentation  
yesterday.

> With the deepest respect for the work done and the obvious good  
> will, may I suggest to focus a lot more on the information provided  
> to the users ?
>
> Maybe allowing some wiki features on the site would allow users to  
> contribute ;-)

I agree that the documentation section should allow editing, even to  
"guest"s perhaps, so that we can all help document it.  I haven't  
felt like creating a new login -- I've been "lurking" as a guest on  
the site.  I keep track of so many passwords, I just want to have one  
less in the world.

> I am convinced ZAP is a tool  anyone developing with PmWiki should  
> consider using.  But the ZAP "packaging" really needs to be a lot  
> more attractive.
>
> Do other persons feel the same ?

Unfortunately yes.  I know for a fact that Caveman is on to something  
terrific, but it's not fast to learn and adopt right now.  An awesome  
plug-in deserves awesome documentation.  I want to write a real  
tutorial for it, but first I have to actually get past learning what  
I'm doing so I can explain it to someone else.  Not seeing the forest  
for the trees, I never would have dreamed up the plug-in that he did  
-- if documentation is not his strength, after all the work he put  
into this, I would love to help document it, package it, so people  
can and will use it.

I also found that when I'm on a snippet page it tells me there are  
requirements, but they're not linked, so I have to search out what is  
required by hunting around through the documentation.  If something  
is referred to that is documented somewhere (or OUGHT to be) on the  
site, it needs a link.

Pages without contents are not showing the ? or any indication that  
they're blank in the sidebar.  It might be ugly, but it helps nag  
people to fill in the blanks.  Without it, it looks like the  
documentation is "complete" -- it's far from complete.

Links on the site are not always obvious.  Hiding links makes looking  
for information a game of hide-and-seek. I don't know about other  
browsers, but on Safari, the text is black, the links are black,  
there are no underlines... I have to play guessing games and run my  
mouse all around the screen to know if something is a link.

Does anyone understand ZAP well enough to help documenting it and  
maybe write an intro-to-ZAP tutorial?

Thanks,

Crisses