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

[Daniel Berlin <dberlin@dberlin.org>]

Sorry for the tone, i've had a frustrating day for other reasons :)

However, my real point still stands:

1. Every developer i've talked to who wants to work on gcc finds our
current docs not useful, both the wwwdocs and the texinfo ones.  Not
because they are out of date, but because they don't give them
information on what they really want to know.
2. If they find the wiki more useful to write down interesting things
they've discovered, how to go about things, or whatever, let them, and
just export the docs from the wiki.  This is simple enough (the wiki
docs are valid xhtml transitional, except for some of the output of
plugins.  But the regular pages are)
3. We should seriously consider writing and maintaining different guides
and references than the ones we have.
I'm happy to go talk to the people who feel this way, and find out what
it is exactly that they want, though i'm pretty sure it's something like

A. Tree language reference guide (ie, semantics, etc)
B. RTL language reference guide (ie, semantics) written in a simple
format like:

RTL Instructions and how they are linked
RTL modes and what they represent.

Then
For each RTL code:

CODE - what it is used for and represents
examples of how operations are represented using CODE
valid flags for CODE
valid macros for CODE

instead of the current:

"here's a bunch of things about rtl.
here's a bunch of things about rtl flags.
Here's a bunch of things about rtl macros.
Here's a small bunch of things about rtl operations.
here's a bunch of things about rtl modes
Here's some more stuff about insns"

C. How to write a basic RTL pass
D. How to write a basic tree-ssa pass
E. Reference guides for analysis providers in tree-ssa (IE what we
provide and how to make use of provided alias info, data dependence
info, immediate uses, etc)
F. Reference guide for analysis providers in RTL.


On Sun, 2005-07-10 at 13:53 -0400, Daniel Berlin wrote:
> 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
>