Metaphors
New authors often have difficulty grasping the finer points of WikiGroups -- in particular,
- the implications for link-syntax in the fact that pages created in one WikiGroup (Site or Main, usually) can be onscreen while one is viewing a page in a different group, and also
- how GroupHeaders, GroupFooters and group-specific SideBars work.
This is a draft of an explanation using a metaphor to try to provide users with a mental hook to something they're more familiar with (enhancements to this, or ideas for alternative metaphors, are more than welcome!).
Wiki site, WikiGroups and pages -- understanding PmWiki's content structure
This website is built using the PmWiki brand of wiki. PmWiki organizes the pages of the site hierarchically in WikiGroups (also known as page-groups). WikiGroups typically contain only pages, and not other, nested, groups -- although there are optional recipes (add-ons, or plug-ins) that can provide additional levels of hierarchy.
A WikiGroup can be thought of as a mini-website within the larger wiki. It will have its own Home Page (its default page), and can have several characteristics that will be shared by default by all of the pages in the group -- characteristics such as password protection and access rights, Headers, Footers, SideBar and uploaded files. The default WikiGroup of the typical PmWiki site is called Main, and the default page of the Main group is usually named HomePage. Each group can also have pages of the same name as in other groups -- for instance, just as each group has its own default page, usually named "HomePage", so (depending on how the site is being used), more than one WikiGroup might have "ContactInformation", "Tasks", "Events", "Resume", pages within it as well.
This much is fairly straight-forward, and may seem unlikely to create confusion, but in fact this structure has implications that are not entirely obvious, and that often trip up new users.
Contents:
Book metaphor
The whole wiki could be compared to a book, its wikigroups to chapters, and pages to pages. Has the advantage of comparing pages to pages. Has the disadvantage of not being as visually compelling as some alternatives.
Multi-volume metaphor
The whole wiki could be compared to a multi-volume set of books, with wikigroups likened to books, and pages to pages. Has the advantage of comparing pages to pages. Has the disadvantage of not being as visually compelling as some alternatives.
Bookcase Metaphor
To illustrate how the pieces all fit together, the metaphor of a bookcase may be useful. Think of the overall wiki as a bookcase. Right at eye level is the default, "Main" WikiGroup, which you can think of as a shelf of books (so that WikiPages in the WikiGroup will correspond to books on the shelf).
Each shelf (WikiGroup) starts out inheriting the security rules for the whole bookcase (wiki site), so that authorization rules for reading or editing any of the books (WikiPages) on any shelf are the same as those for the Main shelf. The usual exceptions to this, at the initial setup of the site, are the Site and SiteAdmin shelves (WikiGroups), which require the "God-level" administrator's password to edit or view, respectively.
Each WikiGroup (shelf) has a default Home Page (usually named "HomePage"), which can be thought of as the central book on the shelf, and serves the purpose of introducing the other WikiPages (books) -- it may be a literal index, or may simply discuss and describe the topic with which the other WikiPages (books) in the group (on the shelf) are concerned. Links on the SideBar of the WikiGroup can be thought of as shortcuts to finding the WikiPages (books) in the WikiGroup (on the shelf). The SideBar is itself a page in the WikiGroup, so can be thought of as a book on the shelf, with content that helps you identify and quickly (via links) grab the other books. The contents of the SideBar WikiPage are visible alongside the contents of each other page in the WikiGroup, so think of this as magically providing an index that appears in the front of every other book on that shelf.
Each WikiGroup (shelf) can have a GroupHeader page and/or a GroupFooter page. These, like the SideBar, are special pages with characteristics that affect all the other pages in the WikiGroup. The content of a GroupHeader appears above the content the other pages in the WikiGroup, seamlessly appearing to be part of each page. This provides a means of unifying the look of the pages of the group. So, for instance, you might have a logo or other image, or a slogan that applies to the group as a whole. This could be placed in the WikiGroup's GroupHeader page, which would cause every page in the WikiGroup to appear to have that material (image or text) at its top. The GroupFooter works the same way, "magically" adding its image or text at the foot of every other page in the group. Think of these pages as books that dictate the appearance of the other books on the shelf. Maybe they control the color of the cover, and part of the label on the front and back.
So the WikiGroup performs several functions:
- It helps to organize content conceptually (put all your books about dogs on one shelf).
- It provides context, in the sense that a page in one group (book on one shelf) will not be confused with a page with the same name in another group (book by the same name on another shelf), because one can specify which group's "ContactInformation" page one is talking about.
- It provides context, in the sense that all the pages in one group have access to, and are 'decorated' or 'embellished' by the same, shared elements (SideBar, GroupHeader, uploaded files, access rules), as all books on one shelf might have the same kind of binding and cover by virtue of their placement on that shelf.
Still to do -- really the point of this whole exercise -- is explaining how links work, especially links between WikiGroups, and why a link on Site/SideBar must be fully qualified.
Hotel metaphor
The wiki is an all-suites hotel; WikiGroups are suites; pages are rooms.
To illustrate how the pieces all fit together, the metaphor of an all-suites hotel may be useful. Think of the overall wiki as a hotel. On arrival, you find yourself in, and having access to, the lobby and other public rooms, analogous to the "Main" WikiGroup, and you can think of each suite as another WikiGroup, so that WikiPages in a WikiGroup will correspond to rooms in a suite.
Each suite (WikiGroup) starts out inheriting the security rules for the whole hotel (wiki site), so that authorization rules for entering or changing any of the rooms (reading or editing any WikiPages) in any suite are the same as those for the rest of the hotel. The usual exceptions to this, at the initial setup of the site, are the Site and SiteAdmin suites (WikiGroups), which require the "God-level" administrator's password to change or view, respectively (and can be thought of as utility and security areas of the hotel). Read and edit permissions can be set on a group-by-group and even page-by-page basis, like controling who can look in through the windows of a suite or room, and who can enter and make changes to a suite or room.
Each WikiGroup (suite) has a default Home Page (usually named "HomePage"), which can be thought of as the central room in the suite, and serves the purpose of introducing the other WikiPages (rooms) -- it may be a literal index, or may simply discuss and describe the topic with which the other WikiPages (rooms) in the group (in the suite) are concerned. Links on the SideBar of the WikiGroup can be thought of as shortcuts to finding the WikiPages (rooms) in the WikiGroup (in the suite). The SideBar is itself a page in the WikiGroup, so can be thought of as a room on the suite, with content that helps you identify and quickly (via links) jump to the other rooms. The contents of the SideBar WikiPage are visible alongside the contents of each other page in the WikiGroup, so think of this as automatically providing air conditioning, lighting and communications services to the other rooms in that suite.
Each WikiGroup (suite) can have a GroupHeader page and/or a GroupFooter page. These, like the SideBar, are special pages with characteristics that affect all the other pages in the WikiGroup. The content of a GroupHeader appears above the content the other pages in the WikiGroup, seamlessly appearing to be part of each page. This provides a means of unifying the look of the pages of the group. So, for instance, you might have a logo or other image, or a slogan that applies to the group as a whole. This could be placed in the WikiGroup's GroupHeader page, which would cause every page in the WikiGroup to appear to have that material (image or text) at its top. The GroupFooter works the same way, "magically" adding its image or text at the foot of every other page in the group. Think of these pages, in addition to the SideBar, as special utility rooms that dictate the appearance of the other rooms in the suite -- so maybe they control the color and style of the walls, carpet and furniture.
In a typical PmWiki configuration, uploaded files are organized by WikiGroup. So you can have two files with the same name (say, Logo.gif, Portrait.jpg, or Status.doc) that are uploaded to two different WikiGroups. Think of these as pictures on the walls and books on the shelves.
So the WikiGroup performs several functions:
- It helps to organize content conceptually (put all your rooms for, say, salespeople in one suite).
- It provides context, in the sense that a page in one group (room in one suite) will not be confused with a page with the same name in another group (room by the same name in another suite), because one can specify which group's "ContactInformation" page one is talking about.
- It provides context, in the sense that all the pages in one group have access to, and are 'decorated' or 'served' by the same, shared elements (SideBar, GroupHeader, access rules, uploaded files), in the way that all rooms on one suite might have the same kind of key-cards, lighting, color-scheme and artwork by virtue of their being in that suite.
Still to do -- really the point of this whole exercise -- is explaining how links work, especially links between WikiGroups, and why a link on Site/SideBar must be fully qualified.