[pmwiki-users] suggested organizing principles for PmWiki documentation
nospam at eton.ca
Tue Jul 26 14:03:35 CDT 2005
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
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 ....
Corporate info at http://www.eton.ca/
Eton Systems, 15 Pinepoint Drive, Nepean, ON, Canada K2H 6B1
Tel: (613) 829-4668
More information about the pmwiki-users