[Pmwiki-users] New structure of Documentation?

[Patrick R. Michaud]

On Sun, Dec 26, 2004 at 01:32:52PM +0100, Laurent Meister wrote:
> the german translation of the documentation is growing and growing. But 
> we have now reached a point, where we discuss some aspects concerning 
> the complete documentation. The main point is the structure of the 
> documentation. There are a lot of things that are repeated on different 
> sites. For example loog at "BasicEditing" and "TipsforEditing".

I'll note that repetition isn't bad.  While it's a nice ideal to try
to make sure everything is described in exactly one location, in reality
it rarely works that way, especially in a hyperlinked environment such
as a wiki.  Sometimes the same information takes on a slightly different
meaning when placed in a different context.  In the example cited,
"BasicEditing" is supposed to be a tutorial about how to quickly
author pages (i.e., when someone is first learning about the wiki), 
while "TipsForEditing" is intended to be a summary overview and quick
reference -- typically coming from the EditQuickReference page.
Since these pages are targeted at authors in different stages of
activity, it's good that information is (redundantly) repeated 
rather than making an author follow links to find the one place
where the information is stored.

That said, TipsForEditing is probably out of date.

> On IRC we talked last week about a new structure for the documentation 
> like:
> [...]
> What do you think about a structure like this?

What follows is not a refutation of the proposed structure, but 
just a clarification of the existing structure so that its design
principles aren't completely lost.  First, let's note that system 
documentation often takes two forms -- "guides" attempt to teach 
the reader how to use a system, while "references" attempt to 
help a reader quickly locate information relevant to a specific task.  
PmWiki's DocumentationIndex has always been intended primarily as
a guide -- i.e., to present pages in a sequence that would
help someone better understand the wiki.  This is reinforced
by the WikiTrail at the bottom of each page, leading the
reader from one page to the next.

I'll note in passing that a few days ago someone reorganized
the DocumentationIndex on pmwiki.org so that all of the 
pages now seems to be in alphabetical order, which might make
things better for reference but completely destroys the
tutorial/guide nature of the documentation and the trail
links at the bottom of the page.  For example, AdvancedTables
now comes before SimpleTables in the trail, which is totally
wrong.  And as far as I'm concerned the TipsForEditing and
TextFormattingRules pages don't belong in the guide sequence --
they're reference pages.  (I haven't decided how/whether 
I want to fix the sequence yet.)

Another aspect of the existing documentation structure is
that it explicitly recognizes the various audiences that
need support: new/naive authors, experienced authors, and
site administrators.  (See PmWiki.Audiences.)  Each of these 
audiences needs documentation tailored to the needs of that 
audience, and each audience may also need both guide and 
reference forms of the documentation depending on the 
task at hand.  Thus, the DocumentationIndex has separate
sections for beginning authors, intermediate authors, 
and site administration.  We shouldn't lose sight of the
fact that the documentation has to serve many audiences.

Perhaps a solution is to have a separate trails for
each audience, such as the BeginnersTrail, AuthoringTrail,
AdminTrail, etc.  Since pages can be stops among multiple
separate trails this might work okay.

That said, here are some initial reactions to the proposed
structure...

> * All About Wiki and PmWiki
> ** About PmWiki
> ** PmWikiPhilosophy
> *  etc.
> * Tutorials
> ** How to Install
> ** etc.
> * detailed explication of all features and functions
> * References (for those using pmwiki, but searching a directives or 
> markups, without long explications)

This structure could be good for admins, but is wrong for
authors.  Someone learning to use the wiki isn't going to
need to know about PmWiki (the package) or the PmWikiPhilosophy 
-- those are for site admins.  What a new author needs to know 
most is how to create and edit pages, how to organize pages, and 
(possibly) how to protect pages or otherwise work in a collaborative
environment.  And this information needs to be most prominent,
since the number of authors will typically be much greater than
the number of admins.  

One of the things that prompted me in 2001 to write my own wiki
rather than use an existing one was that the existing wikis
didn't come with any documentation that I could provide to my
site's users about how to edit pages or use the wiki -- it 
was just "assumed" that everyone knew what a wiki was and how
it worked.

In general I agree that the documentation can use a fair bit
of improvement (I think this is true for almost any system
of any complexity).  Writing good documentation is hard.  But
in changing the documentation structure let's be sure to keep
in mind all of the audiences and needs that documentation is
intended to support.

Comments and feedback highly encouraged.  Especially helpful
are stories of places where the existing documentation
structure hasn't well served someone's needs.

Pm