[pmwiki-devel] ZAP cookbook, www.zapsite.org
crisses at kinhost.org
Thu Dec 7 06:26:06 CST 2006
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
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.
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
> 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 :
> - 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
> 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?
More information about the pmwiki-devel