[pmwiki-users] More Better Documentation . . .

[John McGinnis]

PM, Ben,

 

Gentlemen, the issue that is being danced about as far as updating
documentation and Recipes has to do with definitions not format or layout. I
have been using PMWiki for less than 2 years and I have learned one thing -
PMW is layered like an onion, easy to get going, only slightly harder to
use. But once you get past the initial Wiki experience the real power of PMW
has to be parsed and the first hurdle most encounter is the definitions
associated with the system. Like a dictionary, I know what action I want,
but what feature provides that? If don't know the name then I can't look it
up efficiently. If I don't know the feature then doing a search of
PMWiki.org leads one for a long search trying to match the action with the
feature. Once one is tuned into the lexicon it becomes easier. That has been
my experience. 

 

Personally my suggestions would be:

 

1)       Leave the Recipe format as is. Focus should be on the install and
implementation. Many of the authors provide more than sufficient other
details on other websites.

2)       Some of the docs do need to be 'touched' just to get coverage of
the new features that have been added over the last year. But if it is done
the updates should be added to the existing page, not a new page. Use
colorization to identify these new features from existing ones. (Which I am
seeing in some cases, like in the comments sections)

3)       Add a Category for 'How Do I?...", and an associated page, for
specific actions - adding skins, creating Markup, etc. The trick is to
associate the How with the lexicon, the newbies longest hurdle. 

 

Hope it helps.

 

John McGinnis

 

 

 

 

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: /pipermail/pmwiki-users/attachments/20060524/07c2994c/attachment.html