Re: [Audacity-manual] Tracking changes across pages

[Peter S. <pet...@ya...>]

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

Well I agree with Ed too.
 
having someone on Q/A trawl through the technical details of commit logs is a 
back-to-front way of doing things and far from efficient  - and it would still be far 
too easy to miss changes.
 
Any developer *knows* when they have made a modification to the existing GUI 
(added/removed a check box, re-arranged a dialog box, added a menu item or whatever)
 or added completely new functionality.  I believe that as a fundamental part of the dev 
commit process the developer should be informing the manual team, via this email list, 
of GUI changes that have been committed when they are committted.  This is not an 
onerous additional task and I think it is quite reasonable to ask the developers to do this 
as part of their commit process.
 
It's simply not good enough to just do some development and then leave it for others to 
figure out that the GUI has changed by either noticing the changes when using the program 
or by inference from the commit logs or from the chat on the devel lists.  
 
This is a geographically and temporally spaced project - 
we need some communication here to oil the wheels.
 
My 2c worth ...
Peter.
 
 

Peter Sampson
Tel: +44 (0)1625 524 780
Mob: +44 (0)7732 278 299


________________________________
From: Gale Andrews <ga...@au...>
To: For discussion of Audacity Manual <aud...@li...> 
Sent: Saturday, February 25, 2012 4:49 PM
Subject: Re: [Audacity-manual] Tracking changes across pages


| 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 

------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing 
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/
_______________________________________________
Audacity-manual mailing list
Aud...@li...
https://lists.sourceforge.net/lists/listinfo/audacity-manual