On Tue, 6 Jan 2015, James Greenhalgh wrote:
On Tue, Jan 06, 2015 at 02:56:58PM +0000, Joseph Myers wrote:
On Tue, 6 Jan 2015, James Greenhalgh wrote:
I was aiming to:
* Remove outdated details of the compiler.
* Remove long or obscure words that, while accurate, only served to
obfuscate a simple idea.
* Refer to similar things in a consistent fashion - in particular
trying to keep consistent use of "insn" and "pattern".
* Remove superflous examples, or waffling.
* Update some K&R C and make it use GNU-style.
I've split the patch to a 5-patch series, roughly covering one section
in each.
It would be much more reviewable if the patches were split logically -
each addressing only one of the five issues you mention above - rather
than physically.
That is rather difficult to tease out of a documentation patch without
ending up with a very deep patch stack. Of course such a request is
possible, but often the partial change makes little sense or improvement
without rewriting an entire section, and the burden of making the
intermediary changes read well makes the process of rewriting documentation
exceedingly laborious. Splitting to this granularity essentially requires
a per-paragraph justification.
In reality, a per-paragraph justification of my changes will be easier
for me to provide than a deep patch set. I'll try to find some time one
evening this week to "review" my patches to give this context, if that
would be acceptable.
Hopefully I'll find a few more areas where the text can be improved
along the way!
FWIW, I've had the same dilemma with edits to the GCC user documentation
-- it's too easy to spend a few hours going through the document and end
up with a gigantic patch that is totally unreviewable (because nobody
really wants to take the time to go through tedious mechanical changes
and nobody can identify the substantive changes mixed in with them or
reconstruct your logic for making them). I've concluded that the best
way is *not* to try to maintain a big patch stack, but just to make
multiple passes through the document to fix different types of problems
incrementally. E.g. address markup and grammar issues separately from
rewrites of a whole section, in particular. I have a notepad where I've
jotted down some things I've identified that are in need of fixing while
I've been working on other things in invoke.texi, but no patches beyond
the ones I've already posted and committed.
From time to time I've wondered if we might not be better off moving
towards something like the Wikipedia model for maintaining the GNU
documentation (where everyone can make or revert changes and editors are
encouraged to make changes boldly), but WP's tools are better suited for
that model than Texinfo, patches, and SVN. I do think that taking a
more lenient view of "obvious fixes" for documentation than for code
changes is appropriate, though, since bad doc changes can simply be
reverted and are unlikely to break GCC or hold up other developers' work
meanwhile. It also sometimes (often?) takes months to get code patches
reviewed and such a heavyweight process for documentation changes would
only discourage volunteers from undertaking such work as they have time.
-Sandra
