[Patch docs 0/5] Update some of md.texi

[Sandra Loosemore]

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