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

Tegan Dowling tmdowling at gmail.com
Mon Mar 5 23:25:37 CST 2007


On 3/5/07, Kathryn Andersen <kat_lists at katspace.homelinux.org> wrote:
> On Tue, Mar 06, 2007 at 01:47:47AM +0100, Jan Erik Mostr??m wrote:
> > 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 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.



More information about the pmwiki-users mailing list