Re: Review of the NR

[Phil Holmes]

----- Original Message ----- 
From: "David Kastrup" <address@hidden>
To: <address@hidden>
Sent: Friday, June 21, 2013 12:17 PM
Subject: Re: Review of the NR


> "Phil Holmes" <address@hidden> writes:
>
> > I've just spent a happy few hours reading the NR (pretty much all of
> > it!), and have a list of 41 corrections - they fix things like
> > snippets that should be ragged right, lines too long, some
> > explanations that are no longer accurate, etc., etc.  I guess it will
> > take me a day to fix them.  Do you think it would be better to list
> > them here first, or just go ahead and post a patch for review?
>
> I'd prefer one patch/issue per correction.  But the effort for that is
> not in a realistic relation to the reviewers who are actually going to
> look at it.  It would still be nice if you organized this into separate
> commits (git rebase -i and git add -p can be pretty useful for that kind
> of thing) but it likely does not need more than a single issue in the
> tracker.

Most of them are so small that it wouldn't make sense/be practical to do a 
patch per alteration.  Perhaps the best compromise would be a patch per 
section of the NR - i.e. 5 patches.

> The most important consideration is that you don't do this in a manner
> that leaves you with a "this is the last time I'll ever volunteer for
> something like that" taste in the mouth.

That's why I thought I'd start here.  Reviewers - please remember the 
intention is to improve the documentation, not make it perfect in all 
respects.  When I post proposed changes, please think "is this better?", not 
"is there a slight alternative that will cause a long debate and create no 
improvement?".  In the final analysis, if you have proposed amendments you 
think are better, go ahead and put them up for review.

> --
> David Kastrup
.gnu.org/mailman/listinfo/lilypond-devel
>

--
Phil Holmes