[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:
> First of all, I would suggest that the audiences be kept in mind when 
> creating docs, and I think there are 4 audiences:
> 1) new authors - they need to know how to do simple markup and should not 
> be overwhelmed by options
> 2) experienced authors - they are still primarily concerned with writing, 
> but they want more control over the final layout
> 3) new admins - need to know the minimum amount of stuff to get PmWiki up 
> and running
> 4) experienced admins - want to provide extra features, custom markup, etc.

Gee, this looks an awful lot like 
http://www.pmwiki.org/wiki/PmWiki/Audiences :-)  

I'm not sure I'd split 3 and 4 by "new" versus "experienced" admins;
perhaps the split more properly is between "new admins" and "admins
who want or need to do lots of customizations".

> Third, there should be more overview or index pages like 
> http://www.pmwiki.org/wiki/Cookbook/Cookbook . It is an excellent way to 
> browse recipes of potential interest. It is not just a list of page titles 
> (though that exists too), it actually has a few guiding words about each 
> referenced page, and the pages are organized by topic. 

One of the problems I have with the current Cookbook.Cookbook page is
that the sections are organized alphabetically.  Thus there's really no
indication as to which recipes are the most "popular" or commonly
requested/installed.  Some recipes I think are the best seem to get
hidden in the list... but perhaps that just me.


> The page 
> http://www.pmwiki.org/wiki/PmWiki/DocumentationIndex is a poorer example 
> (but much better than nothing!) because it does not have many capsule 
> descriptions. It would also benefit from the addition of an intended 
> audience indicator for each item.

The sections in DocumentationIndex were already intended to roughly
correspond to the audiences you've identified above; it starts
with information for new authors, then moves to topics of interest
for more experience authors, then information for administrators.
It might benefit from a split between new administrators (who just
want to get things working) and administrators who want to play
with the functionality a bit.

> Fourth, I think there need to be some disambiguation pages added to the 
> docs - that is, pages which identify and attempt to explain easily confused 
> features. A prime example would be a page explaining the difference between 
> userauth.php and authuser.php. ...

Disambiguation notes at the top of pages would be a good idea.  

In the specific case of userauth.php versus authuser.php, the 
PmWiki docs are going to focus on authuser.php as being the
official user-based authorization mechanism, but could have a
link to userauth.php and other recipes for alternate approaches.

> Fifth, there are some pages that need to be ruthlessly deleted or severely 
> edited. The prime example here is http://www.pmwiki.org/wiki/PmWiki/FAQ . 

FAQ has always been a problem; and I totally agree with the "ruthlessly
delete or severely edit" option.

> Sixth (and last), the Sidebar menu should be revisited. Why are the 
> Cookbook and Skins placed under the rubric "pmwiki.org"?  

...because these identify things that aren't properly part of PmWiki,
or at least do not come with the distribution.  All of the rest of
the "main" features come with the distribution.  

But the sidebar is another of those items that I'm expecting will be
heavily reworked as a result of updating the docs.

Pm