Re: [gentoo-dev] Wikis

[Sven Vermeulen]

On Wed, Aug 18, 2004 at 03:57:45PM -0400, Jeremy Maitin-Shepard wrote:
> 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.
[...]
> 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.

Although I certainly support the use of a WiKi (amongst all the other
possible ways to develop documentation) for the development of a certain
document, the problem isn't the medium on which the document is hosted
_before_ it becomes official.

If you want to use OOo's shared document feature to write good
documentation, by all means please do.

Yet once a document is finalised and published on the Gentoo website, it is
important that it remains as static as possible (look who's talking *cough*)
so that:
- users don't get too confused when their favorite document has changed once
  again without having a real content change
- translators don't run away screaming with a big shotgun in their hands to
  kill off that one person that makes their job miserable
- user's don't kill off too many trees by repeatedly printing out documents
  when they have changed

Documentation is a difficult "product". Having statical documentation is a
must, but it must remain bugfree (which is difficult already). I believe
that our current mechanism is the perfect medium for documentation
development (once it is established). 

I support _a_ WiKi as _a_ development platform for _unpublished_
documentation. Once published, I think that a WiKi will put too much
pressure on the document itself as every person can change the entire
document to his or her liking:
- rephraze certain sentences
- use some synonyms to sound more intelligent
- move parts up/down so it fits *your* sense of "Good Documentation" (not
  TM'ed)
- add lots of trivial stuff 
- add lots of "Off The Wall" information
- add huge parts of verbatim text that doesn't really help much
- ...

Wkr,
      Sven Vermeulen

-- 
 ^__^   And Larry saw that it was Good.
 (oo)                                      Sven Vermeulen
 (__)   http://www.gentoo.org              Documentation & PR