Re: [wwwdocs] Make develop.html more readable

[Gerald Pfeifer <gerald at pfeifer dot com>]

On Fri, 1 Aug 2003, Steven Bosscher wrote:
> Again, I think this just looks better and more friendly.

This is a delicate area, and combining reordering of texts with actual
changes made this hard to review, I first tried to extract the actual
changes.

If you want to suggest "simple" moves later, a short textual description
should be sufficient.  "This just looks better and more friendly" may be
true, but is a but tough for a reviewer ;-), and in fact also this patch
contained an (unintended) semantic change!

Those hunks I discuss below are fine, but please do not commit any change
to the document structure (yet).

Index: develop.html
===================================================================
! <p>GCC is one of the largest Free Software projects, driven by a relatively
! incoherent group of contributors with sometimes very different goals.  To
! make sure that the mission and goals of the GCC project itself are met,
! it is necessary to document the development plan employed by the GCC
! community.  This page describes the common goals and the development plan
! for the project.</p>

I may be biased because I recently worked on conference papers where there
are fixed length limits and one has to "optimize" the contents; given that
this doesn't add "hard" information, I'd prefer not to add this (plus such
a prefix may be subject to SC reviewal).

! <p>Typically, suggestions for changes to this plan are discussed on the
! <a href="mailto:gcc@gcc.gnu.org";>GCC mailing list</a> and approved or
! rejected by the <a href="steering.html">GCC Steering Committee</a>.</p>

Good stuff.  Please use "gcc mailing list", put parentheses around this
paragraph, and add it before "Objectives" or in the "footnote" section.

Also, if you'd like to de-footnote-ify [2], omitting the first sentence
on the way, be my guest! ;-)

! <p>The goals of the development plan oulined here are:</p>
                                       ^^^^
Typo, and I'd omit "outlined here" and simply use "this development plan".
(Did I mention that I needed to compress papers recently? <g>)

--- 104,125 ----
! <h2><a name="patchreversion">Patch Reversion</a></h2>

Adding an anchor is fine, and I like the <ul>, but there are some issues,
I'm afraid.

! <p>It sometimes can happen that a patch is committed to the mainline, but
! it introduces a regression <a href="#1">[1]</a>.  To prevent unnecessary
! slowdown in the normal development cycle

Please keep the original version of this, for three reasons:
 (i) it's shorter,
 (ii) you changed semantics (mainline),
 (iii) rationales come afterwards anyways

! the patch may be reverted if
! all of the following conditions are met:</p>

This, and the following list are nice, with minor changes.

! <ul>
! <li>the problem is reported to the original poster;</li>
! <li>48 hours pass without either the original poster or any other party
!     indicating that a fix will be forthcoming in the very near future;</li>

Let's omit "either".

! <h2><a name="future">Release Calendar</a></h2>

Given that this is part of "Release Methodology" and also stages 1-3
are listed there, do you really prefer that? If so, the changes is fine;
I don't feel strongly either way.

Gerald