Re: [Audacity-manual] Tracking changes across pages

[Gale A. <ga...@au...>]

| From Bill Wharrie <bi...@go...> 
| Sat, 25 Feb 2012 11:01:53 -0500
| Subject: [Audacity-manual] Tracking changes across pages
> I have to agree with Ed as well. 
> 
> On 24/02/2012, at 6:01 PM, Bruno Gravato wrote:
> 
> > +1 on what Ed said.
> > 
> > On Fri, Feb 24, 2012 at 10:55 PM, Ed Musgrove
> > <edg...@wa...>wrote:
> > 
> 
> [snip]
> >> 
> >> The comments are almost always meaningless and almost never mention any GUI
> >> changes:
> >>       Correct error trap - compare with what we are expecting.
> >>               Poor--no idea what might be going on.
> >>       Improve font size and colour for track name in waveform pane
> >>               Good--no doubt that it is a GUI change.
> >>       Capitalize heading in line with current style
> >>               suspect this might impact manual, but have to dig into the
> >> code
> >>       Moved /community/donate to its own tab.
> >>               suspect this might impact manual, but have to dig into the
> >> code
> >> 
> >> 
> 
> [snip]
> 
> >> The programmers need to create a rough draft covering the details when they
> >> make code changes which affect the manual but they will not.
> >> 
> >> So, respectfully, "No, thanks!" Lobby the Programmers to consider the
> >> manual, improve their commit comments and document code changes.
> 
> In my view the devs making commits don't need to specifically think about 
> the manual, but a note on functional or UI changes in the commit would be 
> useful.

Hi, 

You are all agreeing with Ed, but not suggesting a lot to prevent Manual
bugs being missed again.

I already said (which comments Ed removed) "we should also encourage 
committers to be aware of changes that will affect the Manual". I would
still put it like that, otherwise they probably won't be thinking of their 
commits in terms of functional or UI changes. They may still need to word
commit logs technically in terms of the code changes that brought about 
the functional/UI changes. 

The other pre-requisites IMO (which no-one commented on):

   "We need a single person who tracks source code changes 
     to take responsibility for tracking required Manual changes.
     When the responsible person is away, they must agree with
     someone else to take over the job while they are away."  

   "We should search for the changed menu items so we catch all
     the pages where changed commands are used." 

"Tracks source code changes" means (at a minimum) receiving the 
commit messages. That would be enough (most of the time) if the devs
thought about the Manual (most of the time) in commit logs. Do you
receive commit messages now, Bill? I think you must, as the Manual 
lead person.  

If then someone (else) also looked inside the code for Manual changes
we would have a very good chance of preventing a recurrence. I would 
volunteer for that, as I do often look inside for quality changes, but I
lack the time until I solely do quality stuff. 

The only other alternative is to reinstate a proof-reading system. I 
think we don't have time for that, even if there was a freeze period
during which there were no code changes affecting the Manual.   





Gale