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

[Jan Erik Moström]

Reply to Tegan Dowling <tmdowling at gmail.com> 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).