Why don't we set up an official wiki for GCC documentation?

Why don't we set up an official wiki for GCC documentation?

[Chunhua Liao]

I find there is a unofficial one www.dberlin.org/gccwiki, but I guess
many people would be reluctant to write something there because there
is no guarantee for its long existence.

Wiki is a good platform for group writing, I know many researchers and
companies are using it as internal documentation platforms. The
results are always encouraging.

Even Mr.Stallman mentioned wiki somehow,
http://www.gnu.org/encyclopedia/free-encyclopedia.html. But I am very
curious why he is not using this for GCC.

The documentation of GCC is a heavily disccussed issue here. I
strongly feel wiki would be a solution for it.

Personally, I prefer MediaWiki to any other wiki engines. There is a
dedicated discussion page for each article and very nice
auto-generated table of contents. Just spend a minute to visit
www.wikipedia.org. I bet you will love it.

The GCC documentation wiki may serve as beta version of the final
formal documentation if somebody worries about its quality.

Again, spend one minute to know about wiki please.

Re: Why don't we set up an official wiki for GCC documentation?

[Joseph S. Myers]

On Thu, 9 Sep 2004, Chunhua Liao wrote:

> Personally, I prefer MediaWiki to any other wiki engines. There is a
> dedicated discussion page for each article and very nice
> auto-generated table of contents. Just spend a minute to visit
> www.wikipedia.org. I bet you will love it.

Although I agree with that preference as far as wikis go - Wikipedia being 
substantially better than the other wiki designs I have seen - I prefer 
getting all commit notifications on gcc-cvs and gcc-cvs-wwwdocs, prefer 
using CVS on the command-line to any web editing system, and dislike that 
gcc-cvs-wwwdocs doesn't include URLs for all the committed diffs (and 
would indeed like all committed patches to go automatically to a mailing 
list, bug 1634).  I also believe the present patch review system generally 
provides the right level of review for patches to the GCC documentation 
(including comments) and webpages (insofar as they form the public face of 
GCC), although it would be better if (a) there were ways of ensuring 
patches didn't fall through the cracks so often, (b) full patches as 
committed automatically went to a mailing list, (c) people didn't approve 
patches without full documentation, (d) people remembered that *all* 
patches, including comment typo and formatting patches, should go to 
gcc-patches (as per cvswrite.html); if nothing else, such patches serve as 
an exemplar to others to avoid the same mistakes.

Ignore this if you wish; it's not an objection to wikis to observe that 
they don't solve the impossible; I'm glad for people to try wikis or any 
other method they think may be useful to improve the quality of the 
manuals, and to hope that some method will succeed and in future all 
patches will include perfect documentation.

Maintaining the quality requirements in GCC development seems (except when 
very optimistic) an impossibly uphill task when so many contributors don't 
take them seriously enough.  Allowing all changes in without prior review 
eliminates a single (and serious) problem - patches falling through the 
cracks - but without solving any of the other problems of maintaining GCC 
and its documentation (5.4 million lines of text) as a consistent, 
coherent and accurate system where documentation need reflect not only the 
code but also interactions with many external systems and specifications.

I have read every message on the main EGCS/GCC mailing lists since EGCS 
started seven years ago and still may sometimes miss the existence of a 
particular convention or not bring to mind at the right time a relevant 
point made in a single mailing list message some years ago.  Developers 
who have been developing GCC for a decade longer still sometimes fail to 
keep properly accurate and consistent documentation.

It's a long time since I tried to go through every patch line-by-line to 
point out every documentation or coding standards defect; many lapses in 
documentation quality and formatting have gone into the GCC manuals since 
I last went through them systematically to clean such issues up.  I have a 
long list of issues to check for in cleaning up manuals retrospectively - 
which is the sort of list for which a wiki *does* make sense, except that 
(a) the list consists of reminders that would be cryptic to anyone else, 
(b) it presumes deep familiarity with the underlying issues which may have 
been alluded to in passing if at all in a few past mailing list messages 
(references not included), (c) it wouldn't actually cause anyone to do 
anything or submit manual patches of better quality.

I have also attempted to document development procedures, quality 
requirements and conventions (in contribute.html, codingconventions.html, 
releasing.html, branching.html, translation.html etc.) so that less needs 
to be induced from an understanding of the 5.4 million lines of source 
tree and 7 years of mailing list messages as a whole.  Occasionally such 
documentation might enhance quality, if for no other reason than that 
having persuaded one person once that a particular statement of a 
requirement is a true and proper statement to go in the procedural 
documentation, it is then there for those trying to ensure quality to 
quote back at those producing patches of inadequate quality.  But any 
effect to enhance overall quality seems limited.  It seems more like the 
effect of writing such documentation is simply to render oneself 
dispensable, as anyone can point out failures to follow what is 
documented, while making little difference in any case to the overall 
results.

One thing you do *not* want a wiki for is anything inviting random user 
questions.  The attempt at putting the FAQ in a wiki-type system 
(FAQ-O-Matic) was a clear failure; it was cluttered up with junk questions 
(not frequently asked) with very few useful user contributions.  Wikis for 
development are likely to work much better than that.

> The GCC documentation wiki may serve as beta version of the final
> formal documentation if somebody worries about its quality.

How do you ensure copyright assignments for all significant contributions? 
Both the GCC web pages and the main GCC manuals require them.

There are certain sorts of collaborative notes on projects under 
development for which wiki is a good way to develop the notes among people 
cooperating on the project and the full CVS system might be overkill.  
The unofficial wiki is a good experiment in this regard with tracking 
project information.  Arranging projects lists in a suitable combination 
of wiki and Bugzilla might be appropriate.  But for anything that might 
end up as design documentation included in GCC (comments, webpages or 
manuals) you need to ensure copyright assignments for those contributing 
significantly.  The summary of memory management in the unofficial wiki is 
something that might end up in the internals manual - I hope we don't find 
there are problems, when wanting to put it there, in identifying all the 
significant contributors to it and being sure they have assignments.

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
  http://www.srcf.ucam.org/~jsm28/gcc/#c90status - status of C90 for GCC 3.5
    jsm@polyomino.org.uk (personal mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Why don't we set up an official wiki for GCC documentation?

[Daniel Berlin]

On Sep 9, 2004, at 10:03 AM, Joseph S. Myers wrote:

> On Thu, 9 Sep 2004, Chunhua Liao wrote:
>
>> Personally, I prefer MediaWiki to any other wiki engines. There is a
>> dedicated discussion page for each article and very nice
>> auto-generated table of contents. Just spend a minute to visit
>> www.wikipedia.org. I bet you will love it.
>
> Although I agree with that preference as far as wikis go - Wikipedia 
> being
> substantially better than the other wiki designs I have seen -

There is a wikipedia skin for the wiki i'm using, i just don't have it 
turned on.
I chose not to use mediawiki because it is heavily biased torwards 
wikipedia, and is somewhat annoying to customize to do what you want.

Anyway, the goal of the wiki i set up is *not* to be a user wiki.
It is for gcc developers, and those learning to develop in gcc, so that 
they can understand the internals, the status of things, etc, in a 
collaborative environment.
In other words, it's for us.  I don't believe we need the same level of 
review for this type of documentation, and i don't think bookmarking 
emails is an ideal solution for anyone (Hands up, who bookmarked the 
link to mark's 3.5 status message in the archives?)

I also disagree with the notion that people won't contribute because 
they are concerned about long term viablility of "dberlin.org" or 
something.
dberlin.org will be around as long as i am.
As a humorous note, we still get people occasionally using 
www.dberlin.org/bugzilla to report gcc bugs.
So people don't seem too concerned that the gccwiki is on dberlin.org

Especially since most developers know me.
I also think a link to the wiki from the "contributing to gcc" page as 
a place to learn about some gcc development internals, projects, etc 
would be a good thing.
There are also things that could be easier kept up to date if they were 
in wiki, and one could just easily, and naturally, edit them.
The list of branches and projects come to mind.  Submitting HTML 
patches for those is kind of annoying and something i have to 
specifically thing about doing, and validating.
Editing a wiki page is not.


--Dan

Re: Why don't we set up an official wiki for GCC documentation?

[Joseph S. Myers]

On Thu, 9 Sep 2004, Daniel Berlin wrote:

> I chose not to use mediawiki because it is heavily biased torwards wikipedia,
> and is somewhat annoying to customize to do what you want.

Sure, it's probably overkill for the present purposes.

> It is for gcc developers, and those learning to develop in gcc, so that they
> can understand the internals, the status of things, etc, in a collaborative
> environment.

And it seems to work reasonably well for that sort of thing.  I just don't 
think the original poster's

> The documentation of GCC is a heavily disccussed issue here. I
> strongly feel wiki would be a solution for it.

bears much relation to how it is useful - the problems with the main 
documentation (manuals and comments) are not something wiki will help 
address, those with projects lists might be though the right relation 
between projects listed in wiki and listed as bugs in Bugzilla needs 
experimentation.

> So people don't seem too concerned that the gccwiki is on dberlin.org

I don't see that as a problem for the present use of the wiki.  It's an 
experiment with the addition of a particular tool to those for GCC 
development, such experiments are to be encouraged, and a move is always 
possible in future anyway.

> The list of branches and projects come to mind.  Submitting HTML patches for
> those is kind of annoying and something i have to specifically thing about
> doing, and validating.
> Editing a wiki page is not.

Whereas I consider any sort of publication involves much the same careful 
due consideration that the change is exactly the change you wish to 
publish, and find editing something in CVS and submitting a patch for duly 
visible review is more convenient and involves less thought than using a 
wiki interface that I use less frequently than CVS / diff and produces 
diff output that looks uglier than the simple plain text output of diff 
-u.  Each to his own.  The wiki provides an additional tool that is useful 
for certain purposes.

(Given the complexity and obscurity of some projects list entries, peer 
review *is* useful before something is removed from a projects list in 
case someone knows of something covered by that entry that has not in fact 
been completed or obsoleted.  Adding projects, clarifying and recording 
the results of discussion of them, etc., need less review.)

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
  http://www.srcf.ucam.org/~jsm28/gcc/#c90status - status of C90 for GCC 3.5
    jsm@polyomino.org.uk (personal mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Why don't we set up an official wiki for GCC documentation?

[Chunhua Liao]

It seems there is a way to get rid of my concerns:
1. a link from gcc official website to your unofficial wiki. Redirect
more developer to your wiki to try it out.
2. a statement on your wiki guaranteeing its enough life for people
don't know you. :-)

  To Joesh: I did not think too much about the license issue or like.
But I am just wondering how wikipedia could survive till today? More
peple would like to doodle on an encyclopedia rather than on a
sophisticated compiler tech site.
  In the worst case, we can still attemp to use wiki as some kind of
internal development cooperation platform, not for outside formal
documentation. A try to new approach is always worthwhile.



On Thu, 9 Sep 2004 13:04:30 -0400, Daniel Berlin <dberlin@dberlin.org> wrote:
> 
> On Sep 9, 2004, at 10:03 AM, Joseph S. Myers wrote:
> 
> > On Thu, 9 Sep 2004, Chunhua Liao wrote:
> >
> >> Personally, I prefer MediaWiki to any other wiki engines. There is a
> >> dedicated discussion page for each article and very nice
> >> auto-generated table of contents. Just spend a minute to visit
> >> www.wikipedia.org. I bet you will love it.
> >
> > Although I agree with that preference as far as wikis go - Wikipedia
> > being
> > substantially better than the other wiki designs I have seen -
> 
> There is a wikipedia skin for the wiki i'm using, i just don't have it
> turned on.
> I chose not to use mediawiki because it is heavily biased torwards
> wikipedia, and is somewhat annoying to customize to do what you want.
> 
> Anyway, the goal of the wiki i set up is *not* to be a user wiki.
> It is for gcc developers, and those learning to develop in gcc, so that
> they can understand the internals, the status of things, etc, in a
> collaborative environment.
> In other words, it's for us.  I don't believe we need the same level of
> review for this type of documentation, and i don't think bookmarking
> emails is an ideal solution for anyone (Hands up, who bookmarked the
> link to mark's 3.5 status message in the archives?)
> 
> I also disagree with the notion that people won't contribute because
> they are concerned about long term viablility of "dberlin.org" or
> something.
> dberlin.org will be around as long as i am.
> As a humorous note, we still get people occasionally using
> www.dberlin.org/bugzilla to report gcc bugs.
> So people don't seem too concerned that the gccwiki is on dberlin.org
> 
> Especially since most developers know me.
> I also think a link to the wiki from the "contributing to gcc" page as
> a place to learn about some gcc development internals, projects, etc
> would be a good thing.
> There are also things that could be easier kept up to date if they were
> in wiki, and one could just easily, and naturally, edit them.
> The list of branches and projects come to mind.  Submitting HTML
> patches for those is kind of annoying and something i have to
> specifically thing about doing, and validating.
> Editing a wiki page is not.
> 
> --Dan
> 
>

Re: Why don't we set up an official wiki for GCC documentation?

[Daniel Berlin]

On Sep 9, 2004, at 1:24 PM, Joseph S. Myers wrote:

> On Thu, 9 Sep 2004, Daniel Berlin wrote:
>> It is for gcc developers, and those learning to develop in gcc, so 
>> that they
>> can understand the internals, the status of things, etc, in a 
>> collaborative
>> environment.
>
> And it seems to work reasonably well for that sort of thing.  I just 
> don't
> think the original poster's
>
>> The documentation of GCC is a heavily disccussed issue here. I
>> strongly feel wiki would be a solution for it.
>
> bears much relation to how it is useful - the problems with the main
> documentation (manuals and comments) are not something wiki will help
> address, those with projects lists might be though the right relation
> between projects listed in wiki and listed as bugs in Bugzilla needs
> experimentation.

I agree wholeheartedly. I don't think wiki is a good solution for our 
documentation right now. Our documentation is mostly in .texi, which 
isn't hard to modify at all.
It's more a social and long standing gcc problem, etc, as you pointed 
out

>
>> So people don't seem too concerned that the gccwiki is on dberlin.org
>
> I don't see that as a problem for the present use of the wiki.  It's an
> experiment with the addition of a particular tool to those for GCC
> development, such experiments are to be encouraged, and a move is 
> always
> possible in future anyway.
>

Right.
This is what i did with bugzilla, after all, so i figured i'd try out 
wiki.
So far, i think it's done fine. We get contributions, etc.
We'll see what it's like in a few months.

RE: Why don't we set up an official wiki for GCC documentation?

[Dave Korn]

> -----Original Message-----
> From: gcc-owner On Behalf Of Joseph S. Myers
> Sent: 09 September 2004 15:04

> Maintaining the quality requirements in GCC development seems 
> (except when 
> very optimistic) an impossibly uphill task 

> It's a long time since I tried to go through every patch 
> line-by-line to 
> point out every documentation or coding standards defect; 
> many lapses in 
> documentation quality and formatting have gone into the GCC 
> manuals since 
> I last went through them systematically to clean such issues 
> up.

> I have also attempted to document development procedures, quality 
> requirements and conventions (in contribute.html, 
> codingconventions.html, 
> releasing.html, branching.html, translation.html etc.) so 
> that less needs 
> to be induced from an understanding of the 5.4 million lines 
> of source 
> tree and 7 years of mailing list messages as a whole.  
> Occasionally such 
> documentation might enhance quality, 

> quote back at those producing patches of inadequate quality.  But any 
> effect to enhance overall quality seems limited.  It seems 
> more like the 
> effect of writing such documentation is simply to render oneself 
> dispensable, as anyone can point out failures to follow what is 
> documented, while making little difference in any case to the overall 
> results.


  Joseph, I first started hacking on gcc back in '99.

  After that, I took a couple of years career break, and came back to it at
the start of this year.

  I was astonished, impressed, stunned, and what's more, very very very
pleased indeed to see the massive improvements to the quality, quantity,
consistency and completeness of the documentation, particularly the
internals.

  Please don't get discouraged; it might seem like a losing battle at times,
but you've made vast progress, even if it doesn't seem like it to you - lots
and lots of little incremental changes never seem like much, but when you
see them all at once like I did, the picture seems very different.  I'm
deeply greatful for your achievements and they've made my job a lot easier
than it was last time I was doing this.

  Thank you very much.

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Why don't we set up an official wiki for GCC documentation?

[Matt Austern]

On Sep 9, 2004, at 10:33 AM, Daniel Berlin wrote:

>
> On Sep 9, 2004, at 1:24 PM, Joseph S. Myers wrote:
>
>> On Thu, 9 Sep 2004, Daniel Berlin wrote:
>>> It is for gcc developers, and those learning to develop in gcc, so 
>>> that they
>>> can understand the internals, the status of things, etc, in a 
>>> collaborative
>>> environment.
>>
>> And it seems to work reasonably well for that sort of thing.  I just 
>> don't
>> think the original poster's
>>
>>> The documentation of GCC is a heavily disccussed issue here. I
>>> strongly feel wiki would be a solution for it.
>>
>> bears much relation to how it is useful - the problems with the main
>> documentation (manuals and comments) are not something wiki will help
>> address, those with projects lists might be though the right relation
>> between projects listed in wiki and listed as bugs in Bugzilla needs
>> experimentation.
>
> I agree wholeheartedly. I don't think wiki is a good solution for our 
> documentation right now. Our documentation is mostly in .texi, which 
> isn't hard to modify at all.

Well, actually our documentation (meaning documentation of compiler 
internals) is mostly in source comments, messages on this list, and 
people's heads.  It would be nice if we had a set of .texi design 
documents that walked through compiler internals, but we don't.

			--Matt

Re: Why don't we set up an official wiki for GCC documentation?

[Joseph S. Myers]

On Thu, 9 Sep 2004, Chunhua Liao wrote:

>   To Joesh: I did not think too much about the license issue or like.
> But I am just wondering how wikipedia could survive till today? More
> peple would like to doodle on an encyclopedia rather than on a
> sophisticated compiler tech site.

They don't require copyright assignments, unlike GCC.  It has been 
reported (e.g. 
<http://lists.debian.org/debian-legal/2003/05/msg00656.html>) that they 
cheated to remove Invariant Sections, infringing contributors' copyright 
by unilaterally changing the licence without everyone's consent.  Unlike 
Wikipedia, licence changes to the GCC documentation are legally possible, 
although unfortunately the FSF have had no interest in changing the 
licence away from the GFDL to one preferred by GCC contributors.

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
  http://www.srcf.ucam.org/~jsm28/gcc/#c90status - status of C90 for GCC 3.5
    jsm@polyomino.org.uk (personal mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Why don't we set up an official wiki for GCC documentation?

[Joseph S. Myers]

On Thu, 9 Sep 2004, Daniel Berlin wrote:

> i don't think bookmarking emails is an ideal solution for anyone (Hands 
> up, who bookmarked the link to mark's 3.5 status message in the 
> archives?)

The problem's not so much emails one thinks to bookmark at the time, as 
those one doesn't.  It's frequent that I recall an email on one of the 
lists on a particular subject from (say) five years ago, but not a 
sufficiently exact date or choice of words or phrases from it for it to be 
easy to turn up the original message.

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
  http://www.srcf.ucam.org/~jsm28/gcc/#c90status - status of C90 for GCC 3.5
    jsm@polyomino.org.uk (personal mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Why don't we set up an official wiki for GCC documentation?

[Stan Shebs]

Daniel Berlin wrote:

>
> [...] I don't think wiki is a good solution for our documentation 
> right now. Our documentation is mostly in .texi, which isn't hard to 
> modify at all.

One win for a wiki in this case is that it's a way to "prototype"
documentation; everybody bang on a description of a neglected area,
converge on something that seems good, then submit as a patch to
the .texi files. The patch process is kind of inefficient for
wordsmithing, as the lengthy doc patch threads suggest.

Stan

Re: Why don't we set up an official wiki for GCC documentation?

[Daniel Berlin]

On Sep 9, 2004, at 4:35 PM, Stan Shebs wrote:

> Daniel Berlin wrote:
>
>>
>> [...] I don't think wiki is a good solution for our documentation 
>> right now. Our documentation is mostly in .texi, which isn't hard to 
>> modify at all.
>
> One win for a wiki in this case is that it's a way to "prototype"
> documentation; everybody bang on a description of a neglected area,
> converge on something that seems good, then submit as a patch to
> the .texi files. The patch process is kind of inefficient for
> wordsmithing, as the lengthy doc patch threads suggest.
>

You guys can use the Wiki for whatever you want. Certainly, I won't 
stop you :)

> Stan
>

Re: Why don't we set up an official wiki for GCC documentation?

[Joseph S. Myers]

On Thu, 9 Sep 2004, Daniel Berlin wrote:

> I agree wholeheartedly. I don't think wiki is a good solution for our
> documentation right now. Our documentation is mostly in .texi, which isn't
> hard to modify at all.
> It's more a social and long standing gcc problem, etc, as you pointed out

Indeed.  I'm confident the people contributing to GCC are all *capable* of 
following the requirements for contributions, including documentation etc. 
- but many don't care.  Personal experience and observation, having 
*written* much of the documentation of contributing procedures, suggests 
that Roger Sayle's description of those capable of following the 
procedures <http://gcc.gnu.org/ml/gcc-patches/2004-07/msg00792.html> looks 
largely like wishful thinking and the supposed personal benefits from 
contributing to GCC in accordance with the procedures do not appear.

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
  http://www.srcf.ucam.org/~jsm28/gcc/#c90status - status of C90 for GCC 3.5
    jsm@polyomino.org.uk (personal mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Why don't we set up an official wiki for GCC documentation?

[Gerald Pfeifer]

On Thu, 9 Sep 2004, Daniel Berlin wrote:
> In other words, it's for us.  I don't believe we need the same level of 
> review for this type of documentation, and i don't think bookmarking emails 
> is an ideal solution for anyone (Hands up, who bookmarked the link to mark's 
> 3.5 status message in the archives?)

That one's not a good example: we (should) have links to the latest
status message for every branch on our gcc.gnu.org main page (and do
most of the time).

> There are also things that could be easier kept up to date if they were 
> in wiki, and one could just easily, and naturally, edit them.
> The list of branches and projects come to mind.  Submitting HTML patches 
> for those is kind of annoying [...]

For branches, and to some extent projects, I'd disagree: just consider
the feedback we often get for patches to these sent via gcc-patches.

Gerald

Re: Why don't we set up an official wiki for GCC documentation?

[Gerald Pfeifer]

On Thu, 9 Sep 2004, Joseph S. Myers wrote:
> it would be better if [...] (d) people remembered that *all* patches, 
> including comment typo and formatting patches, should go to gcc-patches 
> (as per cvswrite.html)

I'll note that web page patches need to be posted to gcc-patches as
well (even after the fact because no approval was needed).  I'm not
going to mention names, but some who missed this recently will also
get this via Bcc. ;-)

> One thing you do *not* want a wiki for is anything inviting random user 
> questions.  The attempt at putting the FAQ in a wiki-type system 
> (FAQ-O-Matic) was a clear failure

Fully agreed.

> The summary of memory management in the unofficial wiki is something 
> that might end up in the internals manual - I hope we don't find there 
> are problems, when wanting to put it there, in identifying all the 
> significant contributors to it and being sure they have assignments.

This is an important point.  Can we enforce that somewho, for example
by only granting those with CVS write access full Wiki access?

Gerald

Re: Why don't we set up an official wiki for GCC documentation?

[Zack Weinberg]

Gerald Pfeifer <gerald@pfeifer.com> writes:

>> The summary of memory management in the unofficial wiki is something
>> that might end up in the internals manual - I hope we don't find
>> there are problems, when wanting to put it there, in identifying all
>> the significant contributors to it and being sure they have
>> assignments.
>
> This is an important point.  Can we enforce that somewho, for example
> by only granting those with CVS write access full Wiki access?

That's not good enough.  Some people with CVS write access don't want
substantial blocks of text that they wrote put into the manual until
its licensing is fixed.  Me for instance.

zw