>>>>> "J" == Jon Stevens <[EMAIL PROTECTED]> writes:
J> Actually, I would rather shy away from Wiki. It tends to get
J> cluttered really quickly and doesn't work that well for
J> documentation. Just ask the Webmacro project. :-)
Anecdotal evidence is not evidence of a pattern ;)
FWIW, I've used Wikis for several projects, some float, others
flounder. If I have seen any pattern at all, it's that collaborative
writing works best when access is open and the tools allow easy, rapid
changes.
The biggest advantage to a wiki is shown by your instructions ...
J> There is no reason why people can't contribute documentation
J> by simply downloading Turbine
J> from CVS
J> and modifying
J> or creating files
J> in the xdocs directory.
J> Just send us patches and new files
J> and they will get checked in.
This is all very clear and fair to people who may be paid to
participate, and I expect a lot of us do this sort of thing in our
day-to-day job so it's not that we don't know _how_. It just seems to
assume a great deal more commitment than I'd expect to see, especially
from people who may (rightly or wrongly) believe they don't know what
they are doing. It begs for caution and care. It doesn't encourage
mistakes ;)
I don't know about you, but I get 1000 times more small email comments
about my code than actual context diffs, probably because a comment,
if it is wrong, is easily forgotten, but a diff takes time and care,
and it hurts a little when they don't take your patch.
One advantage of a web-page community document like Wiki or Jyve is
that people can add little bits of fuzzy knowledge knowing that
someone else can quickly correct it; it reduces the embarrassment
factor.
Another advantage is the low investment of energy. A lot of the
initial kernelwiki was pieced together by browsing the kernel mailing
list for clear Q:A sections and using cut and paste to publish it.
That said, it's not an urgent thing, and yes, given the choice, I
would much rather have documentation that travels with the project in
with the xdocs.
--
Gary Lawrence Murphy <[EMAIL PROTECTED]> TeleDynamics Communications Inc
Business Innovations Through Open Source Systems: http://www.teledyn.com
"Computers are useless. They can only give you answers."(Pablo Picasso)
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
