[pmwiki-users] More Better Documentation . . .

[Ben Wilson]

First, I would like to say my rash of posting is not because I'm
hopped up on some crazy new developer juice. My semester ended with a
whimper on Tuesday and the summer term begins Tuesday next. I'm too
old for school so I'm pushing hard to graduate by Christmas. (Sounds
sort of like very promise at the onset of war--to be home by
Christmas.) Anyway, my wife is humoring my need to program--or more
specifically to clean up half-baked projects over the past several
months. Either way, in 10 days I'll suddenly fall silent.[1]

I know as a Community we pretty much struggle with the issue of clear
documentation. Granted, I've not been as involved with documentation
so when I say we I understand it's more y'all than "me too."

Maybe I have not noticed before, but we have a fair amount of new
users who are asking some good questions. A few of them I thought were
softballs that had answers in the documentation. Then, I went looking
for the documentation.

I know there's a recent discussion on this issue. I need to pay more
attention to that thread. I definitely think we need some "Getting
Started" link right on the front page--above the fold.[2]

We probably also need a more developed "Features" page.[3] Isn't there
a CMS watch type site out there that allows individual wiki to be
ranked side by side? It's been a couple of years since I've
looked--and a hasty google returned bupkiss. Regardless, we might try
listing the Features categorically and help answer why PmWiki stands
out.

We definitely need the time to catch the documentation up. Perhaps
even a tagging system to show what is current. Pm, don't the pages
secret the version of PmWiki that was used to last edit them? If so,
we probably need a pagelist by group to see which are old and which
are new.

Heck, I'd almost encourage setting up a separate wiki field with clean
documentation and start over. A veritable "clean slate." While a fair
amount of material could come directly over, at least it would help us
sort our the cruft. And a fresh set of categories to help guide
neophytes.

-- 
Ben Wilson
" Mundus vult decipi, ergo decipiatur"

[1]: "Ben, what's wrong?" Luke asked. "I felt a great disturbance in
the Force, as if millions of voices suddenly cried out in terror and
were suddenly silenced." That's the sound I hear the day before the
start of classes--millions crying out in terror. When we show up in
class we are suddenly silent as professors prowl about looking for a
student that they can devour with the Socratic (or Sarcastic) Method.

[2]: PmWiki/GettingStarted, which does not exist. I know there's a
PmWiki/EditGettingStarted. We need to have a "walk through" offering.

[3]: http://www.pmwiki.org/wiki/PmWiki/Features is very scant and has
not been revised since December 2004!