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

[Daniel Berlin <dberlin at dberlin dot org>]

On Sun, 2005-07-10 at 19:31 +0200, Gerald Pfeifer wrote:
> I noticed that the Wiki is getting more and more of a third place where
> to find documentation in addition of gcc/doc and wwwdocs, and a parallel
> universe at that, with quite some duplication and inconsistencies.

Have you not yet discovered that this is because people find the
documentation we have to be hard to work with, and submitting patches to
write in texinfo and whatnot to be a pain in the ass? 

Some (maybe most, hard to say) people don't like the organization,
topics, etc of our current documentation.  They find it useless to a
large degree to understand how GCC works.

IE i'm talking about developer facing docs, not user facing docs.

In fact, i had someone recently send me a *104 page PDF file* on how RTL
really works organized in a way that most developers would probably find
better.

But it has some spelling errors, was a little rough, etc.  I'm sure if
he submitted it, it would be nitpicked to death, told to convert to
texinfo, blah blah blah.

However, the fact that he found the current documentation *entirely
worthless* enough to write a 104 page document on how everything
actually worked should tell us maybe there is something wrong with our
documentation implementation, what we cover, and how we cover it.

It's not just "out of date" or whatever, people find it fundamentally
not covering the topics they seem to care about (which is how one
actually goes about doing useful things with our intermediate
representation, etc).


> The Wiki is a nice idea for project lists, "Hot Bugzillas" lists and    
> similar, but when I see pages like http://gcc.gnu.org/wiki/TestingGCC  
> and http://gcc.gnu.org/wiki/HowToPrepareATestcase I really start 
> wondering...

It should make you wonder why people felt it easier to do that than
write it in our "official docs".
Not "why do we have a wiki"?

I find it sad that you are complaining that people have created a
resource *they* find useful, instead of one that *we think they should
find useful*.

In reality, you should be taking the docs people found useful, like on
the wiki, and moving them into our developer facing documentation, etc,
instead of saying what seems to be "we shouldn't let people write about
this stuff on the wiki".


> 
> Michael, why did you take a wwdocs patch and copy it to the Wiki, 
> basically forking our official documentation instead of helping to
> improve it?  I'd appreciate a patch to merge improvements into our
> documentation and help us avoid (and get rid) of this fork.
> 
> Gerald