Hi Raff, Thanks for bringing this up. I agree with Martin, this is a great idea. I think it would be helpful for both the reviewers and the submitters. Best, Martina -----Ursprüngliche Nachricht----- Von: Tei-council Im Auftrag von Martin Holmes Gesendet: Mittwoch, 13. Mai 2020 01:31 An: tei-council@lists.tei-c.org Betreff: Re: [Tei-council] Do we need better issues? I think this is a great idea. My only worry is that relatively non-technical users will be scared away from submitting tickets which (especially in the case of bug reports) really deserve to be submitted. As long as there's some notice along the lines of "if you are not familiar enough with the TEI codebase to complete a proper submission, raise your issue first on TEI-L and then a Council member will help you complete the ticket if it is appropriate." Cheers, Martin On 2020-05-12 3:28 p.m., Raffaele Viglianti wrote:

Hi all,

After today's meeting, I started thinking about why we often end up in loops of discussion. Keeping in mind that this is a partial and personal view, I think that this happens for a few reasons: some are good (e.g. disagreement that needs to be worked out), some are ok (e.g. someone forms an opinion while missing a key piece of context --mea culpa), others are due to the ticket (e.g. it's verbose, it's unclear, it's too short, the discussion is long, etc.)

To address the latter, I think we need to ask more of our submitters (including ourselves when creating issues). Each issue should state clearly what the problem is, show clear examples, and offer a solution. Many issues do (I think of the UVic ones are particularly exemplary, however extreme their requests may often appear to me :) ), but the style varies too much and it makes it time consuming for us to figure out what the real issue is and to reprise quickly on second iterations.

I wonder if a strict issue template may help us here. GitHub allows to configure multiple templates <https://help.github.com/en/github/building-a-strong-community/using-t emplates-to-encourage-useful-issues-and-pull-requests> (e.g. a bug report template could be default, with the possibility to switch to a feature request one, and perhaps others). Templates pre-populate an issue with headers and a description of what's required for consideration, thus at least encouraging a standardized way of formulating a bug report/feature request.

Even if these templates were fairly simple we would still benefit. But I think we could go further and take inspiration from software design documents as a template, which will require the issue reporters to not just do their research, but present it properly too. The DocNow project at MITH creates such documents (publicly) to help discussion within the dev group, and as a crucial means to remind ourselves of why we set to do something (because we all work on dozens of projects and forget things). Here is a very good example https://www.docnow.io/design/2019-05-21-conversation.

I think forcing this on submitters will weed out partially thought out requests, which will always result in us at least wasting time at best closing or getting back to the submitter, at worst engage in loopy "what if" discussions. We have plenty of issues, so I'm not worried about scaring people away. In fact, i wonder if more structure may even encourage less proficient users to contribute more meaningfully. Templates will also give us -- hopefully -- clearer requests with a proposal for a solution built-in.

What do you think?

Finally, if we did choose to use this GitHub feature, we should also look at their recommendations for adding a code of conduct https://help.github.com/en/github/building-a-strong-community/adding-a-code-.... TEI's is hidden deep in the tei-c site https://tei-c.org/about/code-of-conduct/ but we may want to bring it into the repository and close to the issue submitting process.

Thanks for indulging me and I'm well prepared to be told that this in an unnecessary complication and that we should proceed as usual :)

Best, Raff

_______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council

-- ------------------------------------- Humanities Computing and Media Centre University of Victoria mholmes@uvic.ca _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council

Thanks for the encouraging feedback! I'll start drafting templates for bug reports and feature requests and share them with the group for further discussion. Raff On Mon, May 18, 2020 at 9:22 AM Meaghan Brown wrote:

I think this is a great idea. I'd just suggest that maybe the caveat language that Martin was suggesting say something like a "full submission" rather than a "proper submission."

e.g.: "if you are not familiar enough with the TEI codebase to complete a proper *full* submission, raise your issue first on TEI-L and then a Council member will help you complete the ticket if it is appropriate."

On Sun, May 17, 2020 at 2:12 PM Scholger, Martina ( martina.scholger@uni-graz.at) wrote:

...

Hi Raff,

Thanks for bringing this up. I agree with Martin, this is a great idea. I think it would be helpful for both the reviewers and the submitters.

Best, Martina

-----Ursprüngliche Nachricht----- Von: Tei-council Im Auftrag von Martin Holmes Gesendet: Mittwoch, 13. Mai 2020 01:31 An: tei-council@lists.tei-c.org Betreff: Re: [Tei-council] Do we need better issues?

I think this is a great idea. My only worry is that relatively non-technical users will be scared away from submitting tickets which (especially in the case of bug reports) really deserve to be submitted. As long as there's some notice along the lines of "if you are not familiar enough with the TEI codebase to complete a proper submission, raise your issue first on TEI-L and then a Council member will help you complete the ticket if it is appropriate."

Cheers, Martin

On 2020-05-12 3:28 p.m., Raffaele Viglianti wrote:

...

Hi all,

After today's meeting, I started thinking about why we often end up in loops of discussion. Keeping in mind that this is a partial and personal view, I think that this happens for a few reasons: some are good (e.g. disagreement that needs to be worked out), some are ok (e.g. someone forms an opinion while missing a key piece of context --mea culpa), others are due to the ticket (e.g. it's verbose, it's unclear, it's too short, the discussion is long, etc.)

To address the latter, I think we need to ask more of our submitters (including ourselves when creating issues). Each issue should state clearly what the problem is, show clear examples, and offer a solution. Many issues do (I think of the UVic ones are particularly exemplary, however extreme their requests may often appear to me :) ), but the style varies too much and it makes it time consuming for us to figure out what the real issue is and to reprise quickly on second iterations.

I wonder if a strict issue template may help us here. GitHub allows to configure multiple templates <https://help.github.com/en/github/building-a-strong-community/using-t emplates-to-encourage-useful-issues-and-pull-requests> (e.g. a bug report template could be default, with the possibility to switch to a feature request one, and perhaps others). Templates pre-populate an issue with headers and a description of what's required for consideration, thus at least encouraging a standardized way of formulating a bug report/feature request.

Even if these templates were fairly simple we would still benefit. But I think we could go further and take inspiration from software design documents as a template, which will require the issue reporters to not just do their research, but present it properly too. The DocNow project at MITH creates such documents (publicly) to help discussion within the dev group, and as a crucial means to remind ourselves of why we set to do something (because we all work on dozens of projects and forget things). Here is a very good example https://www.docnow.io/design/2019-05-21-conversation.

I think forcing this on submitters will weed out partially thought out requests, which will always result in us at least wasting time at best closing or getting back to the submitter, at worst engage in loopy "what if" discussions. We have plenty of issues, so I'm not worried about scaring people away. In fact, i wonder if more structure may even encourage less proficient users to contribute more meaningfully. Templates will also give us -- hopefully -- clearer requests with a proposal for a solution built-in.

What do you think?

Finally, if we did choose to use this GitHub feature, we should also look at their recommendations for adding a code of conduct < https://help.github.com/en/github/building-a-strong-community/adding-a-code-... . TEI's is hidden deep in the tei-c site https://tei-c.org/about/code-of-conduct/ but we may want to bring it into the repository and close to the issue submitting process.

Thanks for indulging me and I'm well prepared to be told that this in an unnecessary complication and that we should proceed as usual :)

Best, Raff

_______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council

-- ------------------------------------- Humanities Computing and Media Centre University of Victoria mholmes@uvic.ca _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council

-- Dr. Meaghan Brown _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council

Hi Raff, sorry for being late to the party … I really like the idea of issue templates (although I also agree with you that it’s only one part of why it takes us so long). Speaking of templates, I recently came across https://github.com/TEIC/TEI/issues/1914 which might make a good (anti-)model? Here, I like the idea of providing examples but it would really improve the legibility if the issue description was divided into sections, providing a clear structure (with headlines) to see which example illustrates the problem and which the desired outcome/encoding. Many thanks for bringing this up! Best Peter

Am 18.05.2020 um 15:29 schrieb Raffaele Viglianti :

Thanks for the encouraging feedback! I'll start drafting templates for bug reports and feature requests and share them with the group for further discussion.

Raff

On Mon, May 18, 2020 at 9:22 AM Meaghan Brown wrote: I think this is a great idea. I'd just suggest that maybe the caveat language that Martin was suggesting say something like a "full submission" rather than a "proper submission."

e.g.: "if you are not familiar enough with the TEI codebase to complete a proper full submission, raise your issue first on TEI-L and then a Council member will help you complete the ticket if it is appropriate."

On Sun, May 17, 2020 at 2:12 PM Scholger, Martina (martina.scholger@uni-graz.at) wrote: Hi Raff,

Thanks for bringing this up. I agree with Martin, this is a great idea. I think it would be helpful for both the reviewers and the submitters.

Best, Martina

-----Ursprüngliche Nachricht----- Von: Tei-council Im Auftrag von Martin Holmes Gesendet: Mittwoch, 13. Mai 2020 01:31 An: tei-council@lists.tei-c.org Betreff: Re: [Tei-council] Do we need better issues?

I think this is a great idea. My only worry is that relatively non-technical users will be scared away from submitting tickets which (especially in the case of bug reports) really deserve to be submitted. As long as there's some notice along the lines of "if you are not familiar enough with the TEI codebase to complete a proper submission, raise your issue first on TEI-L and then a Council member will help you complete the ticket if it is appropriate."

Cheers, Martin

On 2020-05-12 3:28 p.m., Raffaele Viglianti wrote:

...

Hi all,

After today's meeting, I started thinking about why we often end up in loops of discussion. Keeping in mind that this is a partial and personal view, I think that this happens for a few reasons: some are good (e.g. disagreement that needs to be worked out), some are ok (e.g. someone forms an opinion while missing a key piece of context --mea culpa), others are due to the ticket (e.g. it's verbose, it's unclear, it's too short, the discussion is long, etc.)

To address the latter, I think we need to ask more of our submitters (including ourselves when creating issues). Each issue should state clearly what the problem is, show clear examples, and offer a solution. Many issues do (I think of the UVic ones are particularly exemplary, however extreme their requests may often appear to me :) ), but the style varies too much and it makes it time consuming for us to figure out what the real issue is and to reprise quickly on second iterations.

I wonder if a strict issue template may help us here. GitHub allows to configure multiple templates <https://help.github.com/en/github/building-a-strong-community/using-t emplates-to-encourage-useful-issues-and-pull-requests> (e.g. a bug report template could be default, with the possibility to switch to a feature request one, and perhaps others). Templates pre-populate an issue with headers and a description of what's required for consideration, thus at least encouraging a standardized way of formulating a bug report/feature request.

Even if these templates were fairly simple we would still benefit. But I think we could go further and take inspiration from software design documents as a template, which will require the issue reporters to not just do their research, but present it properly too. The DocNow project at MITH creates such documents (publicly) to help discussion within the dev group, and as a crucial means to remind ourselves of why we set to do something (because we all work on dozens of projects and forget things). Here is a very good example https://www.docnow.io/design/2019-05-21-conversation.

I think forcing this on submitters will weed out partially thought out requests, which will always result in us at least wasting time at best closing or getting back to the submitter, at worst engage in loopy "what if" discussions. We have plenty of issues, so I'm not worried about scaring people away. In fact, i wonder if more structure may even encourage less proficient users to contribute more meaningfully. Templates will also give us -- hopefully -- clearer requests with a proposal for a solution built-in.

What do you think?

Finally, if we did choose to use this GitHub feature, we should also look at their recommendations for adding a code of conduct https://help.github.com/en/github/building-a-strong-community/adding-a-code-.... TEI's is hidden deep in the tei-c site https://tei-c.org/about/code-of-conduct/ but we may want to bring it into the repository and close to the issue submitting process.

Thanks for indulging me and I'm well prepared to be told that this in an unnecessary complication and that we should proceed as usual :)

Best, Raff

_______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council

-- ------------------------------------- Humanities Computing and Media Centre University of Victoria mholmes@uvic.ca _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council

-- Dr. Meaghan Brown _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council _______________________________________________ Tei-council mailing list Tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council