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

[The Editor]

On 12/7/06, Crisses <crisses at kinhost.org> wrote:
> 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.

Thanks Crisses!  I look forward to your help.  Actually I am a teacher
by profession and created zap to make possible an online educational
system.  So I like the teaching side of things, but...

1) I don't really have time to write tutorials on ZAP.  I can't even
keep up with the documentation...  The one tutorial that is up was
submitted by Jiri, and I thought it would be nice to have some for the
more complex applications of ZAP.  Right now I'm working through a
complex Project Management application for someone in Hawaii, when
it's done it will deserve a full tutorial.  Will I take time to write
it, doubtful...  I'll ask him to and see what happens.  But I'd like
users to submit tutorials on complex applications they were able to
get working with ZAP

2) I think the problem may be I'm not a professional coder so what I
think is helpful does not seem to answer the questions regular coders
are asking.  So I'm counting on specific suggestions to pinpoint how I
can revise things into language others will understand.

> 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.

I went ahead and opened up editing for the docs group to anyone.  Just
double click the page to goto the edit mode. As for the asterisk, it
is basically a wildcard.  datapage1, datapage2, etc will trigger the
feature. A long time ago I had a paragraph at the top explaining the
syntax I used in my table.  Now the table is gone, the documentation
is spread out, and there are still a few traces of the syntax here and
there.  Suggestions for how to fix it?

> 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.

It's not set to that. I prefer users to use unique names to see ZAP at
work better.  It's essentially designed to be most powerful as a
membership-based CMS.  I don't care if they are junk accounts.

> 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.

It's not an Iframe, but a redirect within a frame so the URL looks
like zapsite.org. But I changed it to a real redirect to prevent IE
problems.

> 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.

See above.

> >     - 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?

I tried having the source displayed right on the page [@ @] with the
functional code but long lines broke my display, and people were often
asking why it didn't work.  Or I would tweak the code and forget to
change the displayed code.  Or accidently change the display part then
couldn't figure why the function didn't change.  Headache.  When it
struck me to use the source, it solved all those problems.  Changing
it to a real redirect also seems to have solved the source problem for
IE

> >     - 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.

I apologize for the lack of some of the newer features being fully
documented.  If anyone has specific questions about one, I'll be happy
to explain by email directly.  I find that easier than just writing up
docs.  If I do, please help by adding it to the documentation section
somewhere.  I know I've explained the lockpattern thing at least three
times this week in detail.  I've taken to cutting and pasting parts of
emails from one person to another.  Not very efficient...

> > 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.

Actually, the problem may be I'm so into how this code works, I can't
see what's not clear to others.  It *seems* to be so easy and simple I
can't understand why others are struggling.  But that's like the
writer that needs someone else to edit his mistakes.  You kind of get
blind to things you are soooo familiar with.

I'm looking forward to your help, Crisses and others. Thanks to
everyone for taking an interest in this.  It's my first project
remotely like this, and it has exceeded my expectations.  I've
especially enjoyed being part of such a warn and helpful community.

> 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.

Yes, I have it set up for this, but haven't taken the time to make all
the links.  Another area that needs some help.

> 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.

I have that disabled because of virtual pages, like profiles.  There,
I just re-enabled the ugly ?'s for the docs group at least... As an
invitation to edit them...

> 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.

On FireFox, all the links (except the sidebar) show up bold red.
Nothing is showing up on Safari?

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