[pmwiki-users] Does this list inhibit development of good documentation?
Jan Erik Moström
lists at mostrom.pp.se
Tue Mar 6 02:43:43 CST 2007
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).
More information about the pmwiki-users
mailing list