Re: [Teas-ns-dt] A commonly used approach to tracking issues...

[Eric Gray <[e-mail]>]

Shunsuke,

              The potential for “lost issues” is one of my problems with the way that we have been modifying the definitions draft – i.e. – I annotate a version of the draft and changes are made, often removing or relocating my annotations.  It can be hard for me to determine if all of my comments were addressed.

              Since there is no place to go to determine what the expected resolution was, nor is there any direct indication that I agreed with the proposed resolution, the apparent expectation from the authors is that I will again submit comments if my earlier comments were not addressed to my satisfaction.

              To do this, I have to read the latest version of the draft, then read the annotated version of the earlier draft, then try to correlate the modifications (of potentially relocated text) between the two versions.  This is a non-trivial task and not one that I (or most anyone) has time for more than once every few weeks.

              To make matters worse, the draft may be modified (possibly multiple time, and by multiple authors) more than once a week – without making any prior attempt to converge on exactly what changes will be made and how they resolve comments made by other members of the design team, and often without posting or announcing the results.  Hence the comments made against the latest version available to the design team members are hard to map to related text in the modified version, that we may or may not have seen before we start talking about it on a design team meeting.

              I think we are getting better at this, but we will need to get much better before the drafts get adopted by the working group.

              We should already be trying to use methods and processes that we intend to continue using once the WG adopts the drafts – the only exception being the number of people who are likely to create comments requiring resolution.

              As an example, with the Framework draft, I have used separate threads to discuss proposed changes.  After a certain amount of back-and-forth discussion, John and I have been proposing what we believe the rough consensus changes are and – after making sure there is reasonable convergence – making the changes, posting the new version and sending an E-Mail detailing all of the changes made.

              The only changes that have been made that did not follow this model have been extremely minor editorial changes, or other relatively minor changes resulting from restructuring, template, reference update, or RFC Editor policy requirements (many of which occur automatically as a result of the MD/XML conversion process).

              So far, we have not had enough open issues with the framework draft that keeping a spreadsheet to manage the separate issues/threads has been necessary – but I expect that to change.

              A key piece to try to get our heads around is that – at least for all substantive changes – we don’t make a lot of changes without the appropriate level of agreement as to what the changes should be.

  *   When the drafts are individual drafts, it is best to get agreement among the authors/editors.
  *   Once we agree that a draft should be considered a design team product, it is best to get agreement among the members of the design team.
  *   Once a draft is adopted by a working group, it is best to get agreement among the participants in the working group.

              In general, it is a good idea to get agreement _before_ making the changes, and certainly before publishing them.  Often, however, it is too difficult to imagine what the results of making a lot of related changes will actually look like without posting (in not necessarily publishing) a version with all of the currently agreed changes (along with an explanation of any issues encountered in making them – especially any that may have required adjustments to the agreed changes); when this happens, it is a really good idea to have an issues tracking system in place, as this can help both the authors/editors and the readers to determine of all of the agreed issues and resolutions have been implemented.

--
Eric

From: Shunsuke Homma <[e-mail]>
Sent: Thursday, May 28, 2020 9:31 PM
To: Eric Gray <[e-mail]>
Cc: Kiran Makhijani <[e-mail]>om>; Rokui, Reza (Nokia - CA/Ottawa) <[e-mail]>om>; LUIS MIGUEL CONTRERAS MURILLO <[e-mail]>om>; [e-mail]
Subject: Re: A commonly used approach to tracking issues...
Importance: High

+1

Spreadsheet (or Excel file put on a folder anyone can access) would be useful for management/tracking of issues.
# Actually, we might have lost some  issues and comments  raised due to making new files and sharing them with email.

It would be better to sync up  google docs and spreadsheet by marking issue number to each changed place.

Regards,

Shunsuke



On Fri, May 29, 2020 at 1:57 AM Eric Gray <[e-mail]<mailto:[e-mail]>> wrote:
Authors/Editors,

We may not need this at this point but, in other large design team efforts, we have found it useful to track at least the major issues using a spreadsheet (or similar “Issues List”) approach.

Key things to track:

  *   Text/Context (where the issue occurs in the draft – page, section, and position on the page or in the section);
  *   comment/issue with this text (more usefully descriptive, generally, than “I don’t like this text”);
  *   current proposed resolution (change text to <…>, remove text, add further clarification text <…>, reject [provide explanation]).

It can also be useful (but not absolutely necessary) to include the name(s) of the person(s) raising the issue, in order to provide a list of who needs to be happy with the resolution.

One way that this helps is that it keeps the need to plow through iteration after iteration of the draft, trying to find where the text is actually changed (or removed) in each iteration.

As a proof of concept related to this, the “diff” that Kiran showed at today’s meeting showed a lot of “changed” lines that had actually been moved to some other location – effectively making it look as if a lot more changes had been made than actually were made.

--
Eric