[Pmwiki-users] notes on pmwiki documentation

Patrick R. Michaud pmichaud at sci.tamucc.edu
Fri Feb 28 15:49:41 CST 2003


Following up on the previous messages, I've decided to just 
write down a list of standard pages that I think ought to be
provided with the basic PmWiki distribution, but without
displaying the group memberships.  Perhaps this will make
a useful organization scheme more obvious.  The [...]'s
on some items below indicate that the word might or might not
be part of the title.

  WikiWord
  WikiWikiWeb 
  WikiSandbox
  TextFormattingRules  
  WikiGroups
  WikiStyles 
  [PmWiki]WikiStylesAdmin
  WikiTrails
  FreeLinks
  EditQuickReference (appears at bottom of Edit Page)
  QuickReference
  InterMap
  WikiHelp
  SearchWiki
  HomePage
  [PmWiki]Configuration[Guide] or [PmWiki]Setup[Guide]
    [PmWiki]BasicConfiguration[Guide] (?)
    [PmWiki]AdvancedConfiguration[Guide] (?)
  [PmWiki]Installation[Guide] or [PmWiki]Install[Guide]
  [PmWiki]Variables (documents variables avaible for use)
  [PmWiki]Upgrades (how to do upgrades)
  [PmWiki]Philosophy
  [PmWiki]Passwords  or  [PmWiki]PasswordGuide
  WikiGroupsHowTo
  [PmWiki]Files  or  [PmWiki]FilesOrganization
  [PmWiki]ReleaseNotes
  [PmWiki]ChangeLog
  PmWiki
  [PmWiki]Scripts  or  [PmWiki]Modules
  WikiReferences  (references to other WikiWikiWeb resources)
  [PmWiki]AddingCustomMarkup

One could also replace "Guide" with "HowTo" in each of the above cases
and perhaps that would be more self-explanatory (e.g., 
PmWikiConfigurationHowTo).

I can't figure out where to include things like making backups and
restores, installing PmWiki outside of the public_html space, suggesting 
PmWiki improvements, etc.  I'm not sure if these topics should be separate 
pages or if they should be included as part of other pages.  Especially
for guide documents, I like to have all of the steps available on
a single page that can be printed out, and not have to browse through
multiple pages.

Any further comments or ideas greatly appreciated.

Pm


On Fri, 28 Feb 2003, Patrick R. Michaud wrote:

> On 1 Mar 2003, John Rankin wrote:
> 
> > Although most pagenames are {{free link}}s, Group/[[$Title]] works everywhere because we have redefined the $PageNamePattern. We have *not* changed $WikiWordPattern.
> 
> 
> > 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.
> > --
> > Why do terms need PmWiki in the title? What is wrong with just {{configuration}} and {{password}}s? And is there a convention for favouring singular or plural page names?
> 
> Well, if the pages are in the PmWiki group, we probably don't need
> PmWiki in the title.  I.e., a page named "PmWiki.Configuration" works
> for me.  But if the pages go in another group, such as Main, then I
> think that PmWiki belongs in the title to denote that we're talking about
> configuring PmWiki as opposed to some other component (i.e., 
> "Main.PmWikiConfiguration").  
> 
> It still leaves me with the question of where pages should go, while
> "PmWiki.Configuration" clearly makes sense to me, "PmWiki.WikiWord" 
> seems wrong because it's a definition that isn't specific to just PmWiki.
> And "PmWiki.WikiGroup" is uncertain--it has clear connections as a
> definition but it's also fairly specific to PmWiki.
> 
> Also, I've thought a bit about whether authors should favor singular or 
> plural page names, and I haven't come up with a good answer.  Part 
> of me wants to use whichever version is more likely to appear in text, 
> thus do "WikiStyles" and "WikiWord" as page names, and then use 
> {{WikiStyle|s}} and {{WikiWord}}s when the opposite sense is needed.  The 
> downside to this is that one has to remember which pages are named by 
> plurals and which are named by singulars, which argues for 
> consistently using one or the other in all names.  (Not that this will
> happen anyway.) So, I dunno.
> 
> Pm
> 
> 
> _______________________________________________
> Pmwiki-users mailing list
> Pmwiki-users at pmichaud.com
> http://pmichaud.com/mailman/listinfo/pmwiki-users_pmichaud.com
> 






More information about the pmwiki-users mailing list