[pmwiki-users] Re: suggested organizing principles for PmWiki documentation

[Patrick R. Michaud]

On Tue, Jul 26, 2005 at 03:03:35PM -0400, Neil Herber wrote:
> To my mind, some of the recent mailing list postings 
> about styling images and creating user-specified edit forms cross over the 
> border from "author-friendly" to "only-a-geek-would-want-this". Is a bunch 
> of arcane markup really more user-friendly than straight HTML, where at 
> least the user could look up the conventions?

Just wanted to quickly clarify these two items...

The user-specified edit forms were never intended to be author-friendly,
they're intended to be admin-friendly and skin-designer-friendly.  
I don't expect many everyday authors to ever encounter a user-specified
form (indeed, this is why they appear in the Site group and are
protected against edits).

The discussion about image tags is precisely about how we can
make it into an author-friendly form.  Authors will want to be
able to have floating images with borders with captions, and my 
ultimate goal is to make this as easy as writing

    %float framed% http://.../image.gif\\
    Image Caption

...but in order to make sure we don't end up with a syntax that
works only for this one specific application, we have to explore
the design space a bit to make sure we understand the other options
that authors are going to want to use.

As far as whether they're more user-friendly than straight HTML, I'd
have to say "yes" in this instance, especially for the edit forms.  
Getting the HTML correct for the edit forms is a bit tricky -- 
omitting an identifier or hidden field can cause the edit form to 
look as though it's working when it's really not.  Thus 
(:input e_form:) is doing a *lot* more than just standing in for 
a simple <form> html tag.

> But I didn't intend this to be a whine -  I want to suggest some principles 
> for making the documentation more approachable.

My comments to those in a subsequent post... :-)

Pm