[Pmwiki-users] suggestions for the new documentation structure

[Patrick R. Michaud]

On Mon, Oct 18, 2004 at 05:30:55AM -0400, Robert P. J. Day wrote:
> 
>   now that i'm up and running with pmwiki 2, i noticed that the
> documentation pages are still a work in progress, so i thought i'd
> make some suggestions.  

Excellent!  The current documentation structure was created with PmWiki
0.4, and hasn't ever really been reviewed or commented upon that I'm
aware of.

> [...excellent topic outline skipped...]
> obviously, a fair bit of stuff is missing, but the above seems to
> represent what the vast majority of users would want to see fairly
> quickly.
> 
>   thoughts?

Well, it depends on your definition of "user"--I try to avoid the word
"user" because it's too generic, instead, think of "authors" and
"administrators".

The outline you presented above is excellent for administrators, because
it places things in the order an administrator might encounter them when
setting up the software.  But it's not so good for authors--people who
are writing wiki pages but not running the software--because they have
to get past (or overlook) the installation and configuration details
before they get to the sections on creating, editing, and other markups.

The current PmWiki documentation focuses on authors' needs first
(basic and advanced markups), then has a separate section for
administrative stuff.  Perhaps what we need is two separate indexes--
one for authors and one for administrators (fortunately WikiTrails
makes this extremely easy to accomplish :-).

Pm