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

[Shunsuke Homma <[e-mail]>]

I fully agree. And thus, I proposed to use google docs as a tool for
discussing and getting consensus within NS-DT members before reflecting
updates  on xml.
# Unfortunately, though it does not work well...

We may need to define a rule on updates of NS-DT document. For example,
- Someone having proposals or opinions puts them as comments on the Google
Docs
- Editors refer the comments, and modify texts with recording the changes
in logs
- the commenter check the changes, and the changes are fixed if they
satisfy him/her (If some changes don't get consensus, the commenter put
further comments)
- only fixed changes are reflected on xml (xml is updated regularly, e.g.,
after NS-DT meeting)

Or should we prepare a spreadsheet for issue tracker?

Shunsuke

2020年6月13日(土) 0:49 Eric Gray <[e-mail]>om>:

> 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]>gt;; [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]> 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
>
>