Re: Some notes on the Wiki (was: 4.1 news item)

["Giovanni Bajo" <rasky@develer.com>]

Gerald Pfeifer <gerald@pfeifer.com> wrote:

> It was reviewed the very same day it was submitted:
>
>   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00313.html
>   http://gcc.gnu.org/ml/gcc-patches/2004-06/msg00321.html

Yes. And the review was very detailed, and suggested that I had to redone to
work almost from scratch, scattering the infos across a dozen of files in
both WWW and TeX format where they really belong (including Dejagnu's
documentation), *plus* I could also provide the existing page as a tutorial
with references.

I would like to thank you and Joseph Myers for the accurate and fast review.
The point is that it took me already long enough to prepare that patch, and
I never had time (nor will, let me admit) to go back and redo the work in a
different way.

What happened next is that I started providing the link to the gcc-patches
mail over IRC, and then in the list, and then in private mail. And people
were thanking me for it, because it was very helpful. So, I realized that,
while the improvements you suggested were legitimate and correct, that text
was already very useful *the way it is* *right now*. So, it was put in the
Wiki. And I know many people have read it and found it useful. If you want,
you can add a plea at the bottom of the Wiki page, summing the reviews and
asking volunteers to incorporate it into the documentation in the proper
places.

I already expressed my concerns about the way documentation patches work in
other threads. I myself am uninterested in contributing documentation
patches to TeX (and pretty discouraged about the WWW patches, even if I do
that regularly, as you well know). Instead, I contributed many things to the
Wiki. Given the way things like Wikipedia work out, I think we need to
either review our documentation system, or, if there is too much politics
going on with the FSF, accept the fact that the documentation *is* going to
be forked, and setup a workflow to contribute stuff back from the wiki to
the official documentation.

My personal position is that making documentation patches *blocked* by
review (as happens with code) is wrong. The worst thing it can happen is
that the documentation patch is wrong, and the doc maintainer can revert it
in literally seconds (using the Wiki; in minutes/hours using the TeX).
Nobody is going to be blocked by this; no bootstrap will be broken; no wrong
code will be generated. This ain't code. In many common cases, the
documentation will be useful effectively immediatly, and
typos/subtleties/formatting can be refined by others over time.
-- 
Giovanni Bajo