[publican-list] RFC: Supporting RevisionFlag attribute

[David O'Brien]

Ruediger Landmann wrote:
> On 05/07/2010 08:31 AM, misty at redhat.com wrote:
>> I'm concerned about the way that this RevisionFlag feature would 
>> affect the workflow of the content authors.
>>
>> I don't know if everyone works the same way, but I do a lot of 
>> in-place sentence reworking. If I understand this correctly, I would 
>> need to either mark each sentence I change as revised, or mark a whole 
>> paragraph at a time as revised even if I only change a few words. I'm 
>> unclear whether I would need to copy/paste so that I'd have the old 
>> version still in the document, or how that would work.
>>
>> Can we please have some more info on the way this would work from the 
>> author's point of view? I do appreciate that it would make QE's (and 
>> engineering's) job easier.
>>    
> 
> If you're reworking a document to send off for technical review or 
> partner review, you would:
> 
> set <para RevisionFlag="Added"> on a new paragraph (or section) added to 
> the doc
> set RevisionFlag="Changed" for a changed paragraph or section
> leave sections to delete in place for now, but set 
> RevisionFlag="Deleted" on them
> 
I agree with the idea of implementing these attributes to aid revision. 
As for actual highlighting, perhaps we could distribute a couple of 
different ideas for review before we decide on what constitutes Added, 
Changed, or Deleted. We need to be careful not to create something that 
conflicts with or gets confused with our existing visual styles for 
Notes, etc.

> No need to copy and paste paras -- if the reviewer needs to refer to a 
> Changed section, she or he can look at an older version of the doc. 
> They're reading to see whether the doc makes sense *now*.

I wondered about this too. A reviewer might need to recognize that a 
para or section has been changed, and yes it does makes sense now, but 
why was it changed? What exactly was changed? Did it not make sense 
before, was it wrong, or incomplete? If it's easy to refer to the 
previous version of the doc, then this might not be a problem at all. 
Perhaps a question for people involved in QE? This is my only question 
mark about the whole idea.
> 
> Whether you would bother setting it for a change of only a few words is 
> questionable. I'd only set it for a change of a few words if the few 
> words corrected a serious error of some kind, or it was a change 
> specifically requested by the reviewer on a previous review cycle.
> 
Agreed. You'd need to maintain a "I need you to recognize that this was 
changed and that the new version is complete and correct" approach. 
Tagging minor changes and typos is just making work for everyone.

> This parallels what we've already been doing with <remark>s, but makes 
> it much clearer to reviewers as to what the changes are, while not 
> increasing writers' workload over the existing mechanism.
> 
> Cheers
> Rudi
> 

my 2c
-- 

David O'Brien
Red Hat Asia Pacific Pty Ltd

He who asks is a fool for five minutes, but he who does not ask remains 
a fool forever."
  ~ Chinese proverb