[pmwiki-users] suggested organizing principles for PmWiki documentation

[Neil Herber]

At 2005-07-26  12:15 PM -0500, Patrick R. Michaud is rumored to have said:
>  What we
>really need are some organizing principles for the documentation.

One of the problems I have with the current documentation is figuring out 
whether a particular item is a basic feature, an advanced feature, an 
add-on, or whatever. 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?

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

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.

It is quite tempting to extend the number of audiences - for example, 
advanced admins might create their own skins - but having just 4 audiences 
prevents creation of "audiences of one".

Second, I would suggest that each page of the docs be examined to see which 
audience it is intended for and that it should be so marked. If a page 
contains material for more than one audience, it should be split into 
multiple pages or clearly subdivided with audience-related headings.

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

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. That disambiguation page should have a 
prominent link at the *top* (not buried near the bottom under "see also") 
of the two ambiguous pages. I use the term ambiguous here in the sense that 
a new user really has no basis for deciding which recipe would suit them, I 
am not implying that the recipes themselves have ambiguous instructions.

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 . 
It has a very prominent link in the Sidebar, and it does not deliver what 
it promises. I suspect it may be the first and last page that many 
potential users look at. It certainly discouraged me!

Sixth (and last), the Sidebar menu should be revisited. Why are the 
Cookbook and Skins placed under the rubric "pmwiki.org"? All the rest of 
the "main" features are under PmWiki. Once (or if) audience differentiation 
is more prevalent, it would make sense to have one  SideBar entry for each 
audience, probably pointing to a Cookbook-style index page.

That's enough pontificating from me ....


Neil

Neil Herber
Corporate info at http://www.eton.ca/
Eton Systems, 15 Pinepoint Drive, Nepean, ON, Canada K2H 6B1
Tel: (613) 829-4668