Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Mark Trumpold]

HI

I haven¹t been following this thread to closely but one thing that occurred
to me after refecting a little on this discussion was ...

I started back in Sept 06, I love Pmwiki and its relative freedom and so on.
At the beginning I couldn¹t make heads or tails of the cook book and what it
all meant. I hadn¹t even done much with wiki technology either.

So all the wiki jargon, recipes, localhost, setting up permissions and all
was so new. Not to mention PHP scripting. I had no idea what I was looking
for or what answer I needed! So HOW would I have known what I  wanted search
for in the documentation or cook book. If you do manage a search then you
may get ten+ pages were the term is located. The time consumption was/would
be huge. 

To be able to fire of a quick email for a little help or direction was life
saving and in fact kept me interested and active until I was able to a
understand handle much of it. I was able to persist. Also, the amount of
patient help from people on the list was/is AMAZING which only furthered my
persistence in using pmwiki and not turning away.

The documentation is OK and simple enough to understand but when you start
delving into more complex activities and recipes additions it becomes less
intuitive.

I understand the concerns about this list but it invaluable for beginners
and intermediate users.

>From a HS teachers point of view being able to have this list was a
incredible help and as a result my students are in love with wiki and our
website. I know I am not alone ;-)

Last note, I want to thank everyone who has helped me out that has made our
website a success!

That's my two bobs worth

Mark

http://www.ruthtrumpold.id.au/itgswiki/pmwiki.php







___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Dr Fred C]

  In this respect, there _are_ issues in the documentation. For 
example AuthUser <-> UserAuth, many people asked for clarification in 
pmwiki.org.

  

Along the same issue is there are several interpretations and uses for  "templates" in PMWiki.  "XL templates" are for converting pmcommands into different languages (seems "language conversion list" might be a better term), there's autoloading premade template pages into new pages (my enduser view of what a template is), then there's skin templates (which might be better termed "skin parameter list"), etc.  

It also doesn't help clarity when one searches the pmwiki documentation for something like "template", you end up with a laundry list of between 100 or 200 files, in alphabetical order, starting with "AccessKeys" that has little, if anything, to do with templates.  By the time one finally stumbles on the template info you might want, your brain may be so muddled from reviewing who knows how many other pages that weren't at all about what you were looking for, that you don't recognize you've finally found what your are looking for.  

Much of this is related to how PMWiki is generally designed from the code outward to user, rather than user documentation inwards to the code.  Programmers, when given the latitude to do work from the code outwards, will frequently muddle up end user documentation to the point of creating more documentation confusion than clarity.  The various uses of templates, as well as UserAuth/AuthUser, seem to be examples of this at work.  There's undoubtably other examples.  

That said, there's benefits to the freedom of an open source colaborative effort.  It's this feature that in many ways makes the PMwiki as useful as it is, once you figure out how to make it work the way you want.

-- 

Always, Dr Fred C
[EMAIL PROTECTED]



___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Oliver Betz]

Sandy wrote:

[...]

> > IMO PmWiki has a rather good documentation compared to other wikis I 
> > know. One "problem" is that there are so many features to describe.
> 
> The other problem is that there are so many different ways to accomplish 
> the same thing. Some are more secure, others require less computer 

Ack. In this respect, there _are_ issues in the documentation. For 
example AuthUser <-> UserAuth, many people asked for clarification in 
pmwiki.org.

Oliver
-- 
Oliver Betz, Muenchen


___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Sandy]

Oliver Betz wrote:
> Tegan Dowling wrote:
> 
> [What is *wrong* with DocumentationIndex]
> 
>> I'll bet it's the "more ... reference than ... tutorial" aspect --
>> that a new-comer to it encounters the all-too-common, and hugely
>> frustrating situation, in which one new word or phrase is defined in
>> terms of another one, and a new user has not built up enough
>> background in the application to be able to read through, from
>> beginning to end, without being required to memorize and appreciate an
>> unreasonable number of new terms and concepts for a single pass.
> 
> Excellent explanation. Starting with PmWiki several weeks ago, I 
> fully agree with you.
> 
> But it's doable. Opening a bunch of new tabs in the browser for 
> "thing I have to read later" and reading again and again, one gets 
> the picture after a certain time.
> 
> IMO PmWiki has a rather good documentation compared to other wikis I 
> know. One "problem" is that there are so many features to describe.
> 

The other problem is that there are so many different ways to accomplish 
the same thing. Some are more secure, others require less computer 
knowledge, others work better on one installation, etc.

As with the prebundled wikis, whoever does one should start with a 
single common and simple case.

The ease of doing most things can be scary, until have spent enough time 
with the program to trust it. I spent ages with the local server trying 
to figure out what to replace the word "localhost" with.

Cheers!

Sandy







___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Oliver Betz]

Simon wrote:

[...]

> UseMod is a wiki with NO email list. - this is good.

Not in my opinion. I don't want to _discuss_ on a web site (including 
"forums"). Only mailing lists and newsgroups are efficient enough.

Results of a discussion shall go to a more static location.

Oliver
-- 
Oliver Betz, Muenchen


___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[The Editor]

On 3/6/07, Dr Fred C <[EMAIL PROTECTED]> wrote:
>
>  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.

Not sure I agree...  I had the same complaint with zap so I put up
about 40 sample snippets, and a bunch of documentation on the various
commands, with comments, etc.  Still, kept getting questions and even
complaints--because people couldn't figure out how zap worked.
Finally I put up several pages of general info, giving an overview,
and now I rarely get anything but specific questions about specific
applications.  I think that's what we need with PmWiki.

There is a lot of good documentation up already, but I remember when I
started, not understanding at all what went in a config file, what
went in a wiki page, how everything fit together, etc.  I posted
several requests for a good primer and never got much info--though I
had bunches of questions answered.  Questions I see others still
asking today.  So I think a good overview of how PmWiki works would be
helpful.  No time to write it myself, so I'm not complaining.  Just
adding my two cents.

Cheers,
Dan

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Dr Fred C]

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
pmwiki-users@pmichaud.com
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
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Hans]

Tuesday, March 6, 2007, 9:58:09 AM, Francis wrote:

> 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.

You find Pm often added explanations to functions inside the code
scripts. And we started to document major important functions in
the PmWiki group.

> When I started this thread, I was more referring to the
> Cookbookdocumentation than the core documentation - which I see as
> more of a problem, precisely because it is less complete and less well
> organised.

The cookbook is and will always be a work in progress. There are so
many contributors, each with their own style of documenting a recipe.
The cookbook index page Cookbook.Cookbook I agree is much less
organised than the PmWiki.DocumentationIndex. At least we have some
headings now. But recipes under some of the headings do not correspond
to categories, or the headings do not correspond to categories.

There are Administrative Tasks, and Functional Extensions, and quite
different recipes are listed under each, with very different
categories (if any).

Cookbook.Cookbook-ByCategory should automate the indexing of recipes,
and is doing  a good job. But not all recipe pages are updated to use
categories.

I wonder if we can introduce a new heading/category for
pagelist/search recipes?


Hans


___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Francis Casson]

On 06/03/07, Kathryn Andersen <[EMAIL PROTECTED]> 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
Cookbookdocumentation 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
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Jan Erik Moström]

Reply to Tegan Dowling <[EMAIL PROTECTED]> 07-03-05 23:25:

>I'll bet it's the "more ... reference than ... tutorial" aspect --
>that a new-comer to it encounters the all-too-common, and hugely
>frustrating situation, in which one new word or phrase is defined in
>terms of another one, and a new user has not built up enough
>background in the application to be able to read through, from
>beginning to end, without being required to memorize and appreciate an
>unreasonable number of new terms and concepts for a single pass.

I agree.

One of the more important aspects of an introduction to a 
program system is to give the reader a sense of how things are 
organized and give you a sense of what you can do with the 
system, not to learn all the details but to get an quick 
overview. For me this usually stick in the back of my head and 
when I need some feature I remember that the system could do 
something like that and then I can look up the details.

Another example: I'm using three applications more or less daily 
and they are really frustrating. They are excellent all three of 
them and I really try to take advantage of the feature and I've 
read the manuals several times ... the problem here isn't the 
intro, they all have good intros, but the lack of reference 
material, it always feels like I'm just scratching the surface 
of what these apps can do. PmWiki is the opposite, it has a very 
good in-depth documentation. (interestingly, but not 
surprisingly, enough all three apps come from the same company).

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Simon]

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.

UseMod is a wiki with NO email list. - this is good.
Consequently its website (eating its own dog food) is better polished
and up to date.

The longer answer is that it is incumbent on us to
* refer to the seemingly most pertinent documentation we have searched
in our quest for an answer
* update the documentation with the answer after we receive it, or
* if the answer was already there, add a few links and references from
where we thought it would be to where it is.


Documentation isn't a linear or a hierarchical thing.
Its a network.
What we need is content and navigation.

Content is simply a matter of thinking about what needs to be said,
and then writing it down.

Navigation is subtler. Its a personal thing.

PmWiki is admirably provided with navigation through the page and group
structure,
search, categories.

So, its up to you
- use PmWiki more,
- use the mailing list less
- write and refactor

cheers

Simon

PS I use my profile page to list the documentation I find most valuable.


___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Oliver Betz]

Tegan Dowling wrote:

[What is *wrong* with DocumentationIndex]

> I'll bet it's the "more ... reference than ... tutorial" aspect --
> that a new-comer to it encounters the all-too-common, and hugely
> frustrating situation, in which one new word or phrase is defined in
> terms of another one, and a new user has not built up enough
> background in the application to be able to read through, from
> beginning to end, without being required to memorize and appreciate an
> unreasonable number of new terms and concepts for a single pass.

Excellent explanation. Starting with PmWiki several weeks ago, I 
fully agree with you.

But it's doable. Opening a bunch of new tabs in the browser for 
"thing I have to read later" and reading again and again, one gets 
the picture after a certain time.

IMO PmWiki has a rather good documentation compared to other wikis I 
know. One "problem" is that there are so many features to describe.

A introductory manual could improve this even further, but it is not 
easy to do. It should explain only the basics, not too detailed, to 
give the novice an idea how things work. There should not be too much 
redundancy since this would be a maintenance nightmare.

Oliver
-- 
Oliver Betz, Muenchen


___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Tegan Dowling]

On 3/5/07, Kathryn Andersen <[EMAIL PROTECTED]> wrote:
> On Tue, Mar 06, 2007 at 01:47:47AM +0100, Jan Erik Mostr??m wrote:
> > Reply to Tegan Dowling <[EMAIL PROTECTED]> 07-03-05 18:02:
> >
> > >Did the DocumentationIndex actually fail you in that regard (if so,
> > >how?), or did it not appear to be a candidate for that kind of reading
> > >(if not, why not?)
> >
> > The DocumentationIndex is an excellent source of information
> > which I'm starting to find my way around. If you know what
> > you're looking for it's very good but as an overview for a
> > newbie it didn't work for me.
> >
> > One problem with a hyperlike structure is that it's hyperlinked,
> > this is good if you know the "space" but if you're trying to
> > figure out something for the first time a linear "story telling"
> > approach works better ... at least for me.
>
> I'm still confused as to why it isn't possible to read the
> DocumentationIndex "linearly".
>
>  Table of Contents
>
> * Beginner Topics for Creating/Editing Pages
> * Intermediate Editing Topics
> * Wiki Structures: Organizing and Protecting Pages
> * PmWiki Site Administration
> * About PmWiki
>
> Wouldn't one just start with the Beginner topics, go on to
> the Intermediate topics, and so on?
>
> 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?

I'll bet it's the "more ... reference than ... tutorial" aspect --
that a new-comer to it encounters the all-too-common, and hugely
frustrating situation, in which one new word or phrase is defined in
terms of another one, and a new user has not built up enough
background in the application to be able to read through, from
beginning to end, without being required to memorize and appreciate an
unreasonable number of new terms and concepts for a single pass.

It seems to me that this would be the difference, in practical,
new-user terms, between a reference (even linearly organized) and an
introductory manual.  A real introductory manual is written with an
reader of a given level of experience in mind, and also doesn't expect
that the reader has necessarily absorbed/processed all (or even much)
of what came before.

Yet, even an introductory document has to expect the reader to have
absorbed *something* of what has been covered up to each point - else
the author would be re-defining terms every single time they're used.
So the DocumentationIndex's failure in this regard is no condemnation
of its contributors - this is not be an easy balance to strike, even
for a single writer who is composing a document with full anticipation
of his/her reader's situation.   It's just not the strong suit of the
kind of accumulated-wisdom-of-many-contributors thing that we have in
the DocumentationIndex.

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Kathryn Andersen]

On Tue, Mar 06, 2007 at 01:47:47AM +0100, Jan Erik Mostr??m wrote:
> Reply to Tegan Dowling <[EMAIL PROTECTED]> 07-03-05 18:02:
> 
> >Did the DocumentationIndex actually fail you in that regard (if so,
> >how?), or did it not appear to be a candidate for that kind of reading
> >(if not, why not?)
> 
> The DocumentationIndex is an excellent source of information 
> which I'm starting to find my way around. If you know what 
> you're looking for it's very good but as an overview for a 
> newbie it didn't work for me.
> 
> One problem with a hyperlike structure is that it's hyperlinked, 
> this is good if you know the "space" but if you're trying to 
> figure out something for the first time a linear "story telling" 
> approach works better ... at least for me.

I'm still confused as to why it isn't possible to read the
DocumentationIndex "linearly".

 Table of Contents

* Beginner Topics for Creating/Editing Pages
* Intermediate Editing Topics
* Wiki Structures: Organizing and Protecting Pages
* PmWiki Site Administration
* About PmWiki

Wouldn't one just start with the Beginner topics, go on to
the Intermediate topics, and so on?
 
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?

Kathryn Andersen
-- 
 _--_|\ | Kathryn Andersen  
/  \| 
\_.--.*/| GenFicCrit mailing list 
  v | 
| Melbourne -> Victoria -> Australia -> Southern Hemisphere
Maranatha!  |   -> Earth -> Sol -> Milky Way Galaxy -> Universe

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Jan Erik Moström]

Reply to Tegan Dowling <[EMAIL PROTECTED]> 07-03-05 18:02:

>Did the DocumentationIndex actually fail you in that regard (if so,
>how?), or did it not appear to be a candidate for that kind of reading
>(if not, why not?)

The DocumentationIndex is an excellent source of information 
which I'm starting to find my way around. If you know what 
you're looking for it's very good but as an overview for a 
newbie it didn't work for me.

One problem with a hyperlike structure is that it's hyperlinked, 
this is good if you know the "space" but if you're trying to 
figure out something for the first time a linear "story telling" 
approach works better ... at least for me.

I'm the kind of person who actually reads the documentation when 
I start using something, this first overview works best if it's 
linear and builds on what have previously been covered. When 
I've read this I'm ready for the hyperlinked/reference stuff.

Typical example of how I learn something: when I learned Perl 
many moons ago I bought the book "Learning Perl" and read it 
from cover to cover, that got me started. I've never used the 
book again (it's still in my book shelf though) but instead I 
use perldoc etc. Same thing happened when I started to use 
iPhoto, while I directly could use the basic stuff it was too 
much work to figure out how the "advanced" stuff worked so I 
bought a book, read it and have never looked at it again. I 
could continue this for some time.

So I basically use the introduction/overview/manual as a way of 
saving myself some time, I can of course figure out things 
myself (hey, it's my day time work) but why should I do that 
when someone else have done the work and explains it to me?

OK, this might sound lazy but it's just a matter on what I spend 
my time. As I said above, my day-time work is basically just 
this: figure out how things work and then explain it to others 
so they don't have to spend their energy on doing the grunt 
work. It's better that I tell them the basic structure, show 
them the highlights and get them a flying start.

 jem

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Tegan Dowling]

On 3/5/07, Jan Erik Moström <[EMAIL PROTECTED]> wrote:
> Reply to Hans <[EMAIL PROTECTED]> 07-03-05 23:30:
>
> >How did you get on with the PmWiki/DocumentationIndex?
> >Is this page helpful for a start? As a guide perhaps even to read some
> >pages linearly? The documentation pages have also got wiki trail links,
> >with which you can go from page to page, in the order of the links on
> >the DocumentationIndex page.
>
> Personally I would like to learn a bit more about the internals
> of how PmWiki works (so I could understand enough to make
> something myself). What I usually do when I do something like
> this I try to find some PDF that have a good overview/tutorial
> of the subject, print it and read it off-line. I haven't found
> this for PmWiki (perhaps I've missed something) and this
> together with a general lack of time has prevented me to do anything.

Did the DocumentationIndex actually fail you in that regard (if so,
how?), or did it not appear to be a candidate for that kind of reading
(if not, why not?)

Thanks!

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Jan Erik Moström]

Reply to Hans <[EMAIL PROTECTED]> 07-03-05 23:30:

>How did you get on with the PmWiki/DocumentationIndex?
>Is this page helpful for a start? As a guide perhaps even to read some
>pages linearly? The documentation pages have also got wiki trail links,
>with which you can go from page to page, in the order of the links on
>the DocumentationIndex page.

Personally I would like to learn a bit more about the internals 
of how PmWiki works (so I could understand enough to make 
something myself). What I usually do when I do something like 
this I try to find some PDF that have a good overview/tutorial 
of the subject, print it and read it off-line. I haven't found 
this for PmWiki (perhaps I've missed something) and this 
together with a general lack of time has prevented me to do anything.

 jem

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Kathryn Andersen]

On Mon, Mar 05, 2007 at 11:18:17PM +, Keith Edmunds wrote:
> On Mon, 5 Mar 2007 10:07:03 +1100
> Kathryn Andersen <[EMAIL PROTECTED]> wrote:
> 
> > Lovely idea -- but part of the difficulty is in trying to figure out
> > what the "relevant place" *is*.

> The problem, I think, is that wikis use themselves to document (quote
> dogfood mantra), which is great if you know what it is you're trying to
> find out (if you see what I mean). What I wanted, however, was the
> equivalent of a reference manual that I could read from start to finish.
> No, I wouldn't remember all the detail, but I would remember what was in
> there, so that subsequently I could lookup the detail of how to accomplish
> a given task.
> 
> The most frustrating thing with pmWiki is that it is very powerful, but
> there is no ONE place to go to find the detail. Instead there are many
> pages of information, each of which cross-reference others (in wiki
> style). At the start, we just want to read it linearly.

I thought that PmWiki/DocumentationIndex was a good place to start.
At least, I found it useful myself.  Where does it fall down?

But while Cookbook/Cookbook is *supposed* to be the equivalent to the
PmWiki/DocumentationIndex for recipes, many people don't add their
new recipes to that page, either because they're scared off because the
page has a password (which is "quick", btw), or because they don't see
the need.

Kathryn Andersen
-- 
 _--_|\ | Kathryn Andersen  
/  \| 
\_.--.*/| GenFicCrit mailing list 
  v | 
| Melbourne -> Victoria -> Australia -> Southern Hemisphere
Maranatha!  |   -> Earth -> Sol -> Milky Way Galaxy -> Universe

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Hans]

Monday, March 5, 2007, 11:18:17 PM, Keith wrote:

> The most frustrating thing with pmWiki is that it is very powerful, but
> there is no ONE place to go to find the detail. Instead there are many
> pages of information, each of which cross-reference others (in wiki
> style). At the start, we just want to read it linearly.

How did you get on with the PmWiki/DocumentationIndex?
Is this page helpful for a start? As a guide perhaps even to read some
pages linearly? The documentation pages have also got wiki trail links,
with which you can go from page to page, in the order of the links on
the DocumentationIndex page.
Maybe the trail links should be put more prominently, perhaps on top
of the content, as in the Cookbook pages?


Hans


___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Keith Edmunds]

On Mon, 5 Mar 2007 10:07:03 +1100
Kathryn Andersen <[EMAIL PROTECTED]> wrote:

> Lovely idea -- but part of the difficulty is in trying to figure out
> what the "relevant place" *is*.

Good point. I've just come to pmWiki, and - despite more years than you
want to know of IT experience, programming, wiki-playing, et al - I found
it hard to get a basic understanding of how pmWiki works.

The problem, I think, is that wikis use themselves to document (quote
dogfood mantra), which is great if you know what it is you're trying to
find out (if you see what I mean). What I wanted, however, was the
equivalent of a reference manual that I could read from start to finish.
No, I wouldn't remember all the detail, but I would remember what was in
there, so that subsequently I could lookup the detail of how to accomplish
a given task.

The most frustrating thing with pmWiki is that it is very powerful, but
there is no ONE place to go to find the detail. Instead there are many
pages of information, each of which cross-reference others (in wiki
style). At the start, we just want to read it linearly.

K.

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[marc]

Kathryn Andersen said...
> On Sun, Mar 04, 2007 at 05:27:00PM +, Francis Casson wrote:
> > Many people (including myself) come to this list after failing to find the
> > answer we need in the documentation on PmWiki.org - or not understanding it.
> > 
> > I propose encouraging the following mailing lists ethic:  If you seek the
> > answer to a question and find it on the mailing list, then you should add
> > the question and answer to the relevant place(s) on PmWiki.org - This way
> > the documentation will improve, FAQs will need repeating less often, and
> > long term the traffic on this list will go down.
> 
> Lovely idea -- but part of the difficulty is in trying to figure out
> what the "relevant place" *is*.

:-)

Yup, wikis need the XP (extreme programming) task of 25% refactoring. 
They are certainly not self-managing, ime.

-- 
Cheers,
Marc


___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users

Re: [pmwiki-users] Does this list inhibit development of good documentation?

[Kathryn Andersen]

On Sun, Mar 04, 2007 at 05:27:00PM +, Francis Casson wrote:
> Many people (including myself) come to this list after failing to find the
> answer we need in the documentation on PmWiki.org - or not understanding it.
> 
> I propose encouraging the following mailing lists ethic:  If you seek the
> answer to a question and find it on the mailing list, then you should add
> the question and answer to the relevant place(s) on PmWiki.org - This way
> the documentation will improve, FAQs will need repeating less often, and
> long term the traffic on this list will go down.

Lovely idea -- but part of the difficulty is in trying to figure out
what the "relevant place" *is*.

Kathryn Andersen
-- 
 _--_|\ | Kathryn Andersen  
/  \| 
\_.--.*/| GenFicCrit mailing list 
  v | 
| Melbourne -> Victoria -> Australia -> Southern Hemisphere
Maranatha!  |   -> Earth -> Sol -> Milky Way Galaxy -> Universe

___
pmwiki-users mailing list
pmwiki-users@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users