<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
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. <br>
<br>
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. <br>
<br>
Francis Casson wrote:
<blockquote
cite="mid7c2c95c80703060158u7b22b8a7mf47eacb352969e98@mail.gmail.com"
type="cite"><span class="gmail_quote"></span><span class="q"><span
style="color: rgb(51, 51, 255);">On 06/03/07, Kathryn Andersen <<a
href="mailto:kat_lists@katspace.homelinux.o" target="_blank"
onclick="return top.js.OpenExtLink(window,event,this)">
kat_lists@katspace.homelinux.o</a></span><span
style="color: rgb(51, 51, 255);">rg> wrote:</span><br
style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);">> </span><br
style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);">> What is *wrong* with
it? Are the Beginner topics too advanced?</span><br
style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);">> Conversely, is there a
lack of "advanced" topics?</span><br style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);">> Or is it that it is more
of a reference than a tutorial?
</span><br style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);">> </span><br
style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);">> </span><br>
</span>For me, I was able to learn most basic stuff that I needed
from the Documentation Index, with a little effort.
<br>
More advanced topics such as eexplanations of the PmWiki code would be
useful though.<br>
<br>
When I started this thread, I was more referring to the <span
style="color: rgb(204, 0, 0);">Cookbook</span> documentation than the
core documentation - which I see as more of a problem, precisely
because it is less complete and less well organised.
<span class="q"><br>
<br>
<span style="color: rgb(51, 51, 255);">On 06/03/07, Simon <<a
href="mailto:s-i-m-o-n@paradise.net.nz" target="_blank"
onclick="return top.js.OpenExtLink(window,event,this)">s-i-m-o-n@paradise.net.nz
</a>> wrote:</span><br style="color: rgb(51, 51, 255);">
<br style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);"> I think the short answer
is yes.</span><br style="color: rgb(51, 51, 255);">
<br style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);"> It is tooo easy for a
quick question to be flicked off,
</span><br style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);"> instead of ''reading the
documentation''.</span><br style="color: rgb(51, 51, 255);">
<br style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);"> Thinking about what you
want and reading documentation is hard,</span><br
style="color: rgb(51, 51, 255);">
<span style="color: rgb(51, 51, 255);"> getting someone else to
think for you is easy.
<br>
</span><br>
</span><span class="q">
<pre
style="color: rgb(51, 51, 255); font-family: arial,sans-serif; margin-left: 40px;">So, its up to you
- use PmWiki more,
- use the mailing list less
- write and refactor
</pre>
</span><span style="color: rgb(51, 51, 255);"><br>
<span style="color: rgb(0, 0, 0);">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.
<br>
<br>
</span></span>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
<br>
<span class="sg"><br>
Francis<br>
<br>
<br>
<br>
<br>
<br>
<br>
</span>
<pre wrap="">
<hr size="4" width="90%">
_______________________________________________
pmwiki-users mailing list
<a class="moz-txt-link-abbreviated" href="mailto:pmwiki-users@pmichaud.com">pmwiki-users@pmichaud.com</a>
<a class="moz-txt-link-freetext" href="http://www.pmichaud.com/mailman/listinfo/pmwiki-users">http://www.pmichaud.com/mailman/listinfo/pmwiki-users</a>
</pre>
<pre wrap="">
<hr size="4" width="90%">
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
</pre>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Always, Dr Fred C
<a class="moz-txt-link-abbreviated" href="mailto:drfredc@drfredc.com">drfredc@drfredc.com</a></pre>
</body>
</html>