Re: [gentoo-dev] Wikis

[Jeremy Maitin-Shepard]

Corey Shields <cshields@g.o> writes:

> [snip]

> I really can't support an official wiki.  If our current method of
> documentation and support totally sucked then it would be a different story,
> but we are known for excellent documentation, and there is a system of checks
> and balances in the documentation process that you just don't get from a
> wiki.  Otherwise, you end up with phrases like "While most poeple use would
> use this : "  which makes no sense (taken from the first page I visited at
> the above url).  I feel that a wiki would be taking a step
> backwards..

I wasn't thinking of using a wiki to host the documentation currently
maintained by the documentation team.  Rather, it could be used for
posting less formal descriptions and status updates relating to specific
projects -- it would surely be more convenient than breaking out Guide
XML, not to mention the various other tasks required for posting it on
the web site, and would thus likely lead to more information being
available.  If a page in the wiki developed into something ready for
posting as official documentation, it could be converted to Guide XML,
either manually or in part automatically by the wiki software.

> If there is a piece of documentation that someone has written and
> feels it should be included, by all means, post it to bugs.gentoo.org.
> While I can't speak for them, I'm pretty sure that the documentation
> team would love the contribution.

Particularly for users, a wiki would not only provide a place to post
less formal tutorials, but also a convenient staging ground for possible
future official documentation.  Right now, there are only two places for
such documents: the forums, which isn't particularly well suited for
various reasons, and as official documentation on the documentation
page.  There is no middle ground, and so a user in particular is
unlikely to go the route of official documentation.  Consider that for
an initial revision of some tutorial, a user is likely to post it to the
wiki rather than the forums (as is done currently), but is not likely to
revise it sufficiently and write it in Guide XML such that it is
approved as official documentation.  Consider in particular that many of
the better howtos and tutorials in the forums have developed into their
current state through various updates over a period of time, starting
From initial versions that were much farther from official
documentation.

> As for the earlier comment that a wiki could be used in place of a
> planet site, that's like using Excel to write your letters.  Sure, you
> could do it, but it's not the best tool for the job.

Perhaps more like using LaTeX to write all your letters. (which I do) ;)

Seriously though, when I made that comment, I had not visited Planet
Gnome and so I did not realize that something for personal and not
project-related content was being proposed.  I agree that for a personal
log with entries like "I read Great Expectations today," a wiki is not
particularly suitable.  I don't think we need an official place for such
content though, while I *do* think we need a place for the sort of
content I describe above.

-- 
Jeremy Maitin-Shepard