[Pmwiki-users] notes on pmwiki documentation

[Patrick R. Michaud]

This is going to be a somewhat rambling document outlining my thoughts-to-date
about how to structure the documentation for PmWiki.  I'm looking for
reactions, opinions, suggestions, and assistance in creating the
documentation.  Although I can certainly write the documentation myself,
I think the quality of the documentation will be much better whenever 
people unfamiliar with the internals of PmWiki (i.e., pmwiki-users) describe 
how it works for them, and then I can correct and update any 
technical inaccuracies from what is contributed.

One general thought I have about documentation is that we need to
explicitly recognize that PmWiki has two distinct classes of users,
which I will term WikiAuthors and WikiAdministrators.  WikiAuthors
are people who create and edit the pages of a wiki system.  WikiAdministrators
are the people who install, configure, and customize a PmWiki-based
installation.  

A WikiAuthor needs to know how to edit a page, how to create links to 
other pages, and the types of markups available within a page.  WikiAuthors 
also need to know how to organize pages into logical structures (groups,
WikiTrails) and how to password protect pages.

A WikiAdministrator needs to know how to download and install the 
PmWiki software, how to customize the look and feel of the installation,
how to enable/disable/customize various PmWiki features, how to manage 
WikiGroups and passwords, and how to manage upgrades when new versions of
PmWiki are released.  They also need to know how to do system-level
things such as backups and restores, how to handle problems encountered by 
WikiAuthors, etc.

So, I think that any pages that we create need to recognize that each
topic may have at least two audiences.  For example, the documentation
for WikiStyles for authors needs to tell people about the available
style markups within a document, while the WikiStyles documentation for
administrators ought to indciate the types of customizations that
are available.  (Maybe this implies a dual-page distinction, e.g.,
"WikiStyles" for authors and "WikiStylesAdmin" or "WikiStylesCustomization"
for administrators.)

In the Unix world we often make a distinction between "guides"
and "reference" documentation.  A "guide" is usually written in a tutorial
or explanatory format, walking the reader through the features of a system
in a sequence that is easy to follow.  A "reference" is usually written
to quickly provide all of the details about a feature.  Both WikiAuthors
and WikiAdministrators will want reference and guide materials for the
tasks they are trying to accomplish.  (A suggestion, perhaps all
"guide" materials should conventionally begin with the WikiPhrase 
"HowTo...", as in "HowToCreateACustomWikiStyle"?)

One of the fundamental documentation questions I have about organizing
the PmWiki documentation is "where do the pages belong"?  Currently the
documentation is split between the "Main" and "PmWiki" WikiGroups,
and it's not always obvious (to me at least) where individual 
documentation pages should go.  I can't decide if there should even
be a split--maybe all of the documentation belongs in Main, where
it can be easily referenced and linked by the most naive WikiAuthors.

>From time to time I feel that there should be a "Reference" or "Dictionary"
group to hold common (Pm)Wiki definitions like WikiWord, WikiWikiWeb, 
WikiGroup, WikiTrail, etc.  But the problem with sticking these pages 
into another group as opposed to Main is that an author has to understand 
WikiGroups in order to be able to access those pages effectively.  
Perhaps that's not a real problem--I'd like to hear from others.

Also, it might be useful to come up with some consistent naming choices
about when to include "PmWiki" in the document.  For example, I've documented
some features like "PmWikiConfiguration" and "PmWikiPasswords", while other
features do not contain PmWiki in the title, as in WikiStyles, WikiTrails,
InterMap, etc.

Anyway, that's about as far as I've gotten on the documentation ideas,
and I could really use some feedback/suggestions, or to just hear other
people's opinions about what they'd like to see in the PmWikiDocumentation.
I'm also declaring "open season" on the PmWikiDocumentation that currently
exists on the pmichaud.com site--feel free to break any of the existing
documents, categories, and structures that are currently there.  Most
of the existing documentation has been created without any master plan 
in mind, and I think a wholesale cleanup would be useful.

Dawn Green has already contributed some useful suggestions and starting
points at http://www.pmichaud.com/wiki/PmWiki/PmWikiDocumentation, perhaps
this is a good starting point.

Thanks again everyone for your contributions.

Pm