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