IMHO, the real problem isn't so much the documentation, which does vary
in ease of use and understandability. For the most part, cookbook use
is dead simple. Install a cookbook file to the cookbook folder and
enter some simple line of code in the local config file. Then start
using the feature.
IMHO, this is where the problem really lies. A fair amount (but not
all) of cookbook documentation provides little to no workable examples
of the cookbook features in actual use. Instead, everyone basically
has to reinvent the wheel over and over, which requires attempting to
comprehend the documentation. Where documentation lacks good examples,
the documentation tries to explain relatively simple stuff using jargon
rather than by example (plus jargon). It's like you trying to tell
someone how to get dressed with both of your eyes closed and they must
follow your instructions literally. This simple process typically ends
up a tangled mess. However, once one figures out how to do it,
magically everything starts to make sense and you're ready to move on.
Go figure.
Francis Casson wrote:
On 06/03/07, Kathryn Andersen <
[EMAIL PROTECTED]rg> wrote:
>
> What is *wrong* with
it? Are the Beginner topics too advanced?
> Conversely, is there a
lack of "advanced" topics?
> Or is it that it is more
of a reference than a tutorial?
>
>
For me, I was able to learn most basic stuff that I needed
from the Documentation Index, with a little effort.
More advanced topics such as eexplanations of the PmWiki code would be
useful though.
When I started this thread, I was more referring to the Cookbook documentation than the
core documentation - which I see as more of a problem, precisely
because it is less complete and less well organised.
On 06/03/07, Simon <[EMAIL PROTECTED]
> wrote:
I think the short answer
is yes.
It is tooo easy for a
quick question to be flicked off,
instead of ''reading the
documentation''.
Thinking about what you
want and reading documentation is hard,
getting someone else to
think for you is easy.
So, its up to you
- use PmWiki more,
- use the mailing list less
- write and refactor
I would contend that most people
at least look at the documentation first, because of the embarrassment
factor of asking a stupid question. But often they don't understand
what is there because it is at too high a level, or is not organised
very well - and then have to resort to the mailing list. Having looked
at the documentation they then know where they would have liked to have
found the answer and can then add it.
I wasn't advocating doing away with this list, but
encouraging those
that get answers here to write them up for the documentation - a way of
giving something back. This should be a more explicit ethic for the
mailing list - it is harder to ignore such an obligation if it is
explicit and promoted - perhaps both on the mailing list description
page and the list itself
Francis
_______________________________________________
pmwiki-users mailing list
[email protected]
http://www.pmichaud.com/mailman/listinfo/pmwiki-users
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.5.446 / Virus Database: 268.18.7/711 - Release Date: 3/5/2007 9:41 AM
--
Always, Dr Fred C
[EMAIL PROTECTED]
|
_______________________________________________
pmwiki-users mailing list
[email protected]
http://www.pmichaud.com/mailman/listinfo/pmwiki-users
