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
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