[Pmwiki-users] Examples in documentation pages -- e.g. WikiTrails

Christian Bartolomaeus bartolin
Fri Dec 31 11:53:48 CST 2004


Hi,

while translating the page WikiTrails for the German documentation
(and remembering my initial difficulties with the WikiTrail-Feature)
I thought, it would be useful to add another little example explaining
the structure and the effect of the 'trail pages'. You could find it
at http://www.pmwiki.org/wiki/PmWiki/WikiTrails. If you have comments
about my change, I'd like to hear them.

But, more importantly, I'd like to know, what you think in general
about extending the documentation by using more examples (without
having certain pages in mind right now). For my understanding this has
the advantage, that users (especially authors) could easily see how a
feature works -- particularly when dealing with a complex feature.

The disadvantages of using more examples:
* At least some documentation pages would get substantially longer,
  which might frighten readers away.
* Some readers might be tempted to skip the abstract documentation and
  to just copy the examples. That way they might miss important
  points and wouldn't get a 'deeper understanding'.

Personally, I have no problems with extensive documentations. So in
case of doubt I would tend to give an additional example. What do you
think?

Christian
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 232 bytes
Desc: not available
Url : /pipermail/pmwiki-users_pmichaud.com/attachments/20041231/3d69646e/attachment-0001.bin


More information about the pmwiki-users mailing list