Intent Open - contribution model

[dginev]

Goal:

Enable an active contribution flow from the larger STEM community for the Intent Open List.

---

Moving from #69, in reply to #69 (comment) :

@NSoiffer the discussion about github hosting for the intent lists was years ago, I participated in it.
The open.yml file appears to have been originally checked in May 2023.

Since then, there are no PRs for the Open list - I think never have been. No contributions safe for @davidcarlisle massaging a few bits. I've contributed plenty to the Core list since, but zero contributions to this new Open list. That is a red flag - I suggest we start considering the current Open list experiment as a "collaborative failure" (one internal to the WG).

My primary problem isn't with Github PRs or YAML, but with the absence of real stewardship for an "Open" project. You've repeatedly mentioned that the load on the senior members is too high to manage the spec work for MathML 4. And this list isn't a primary interest for either of you, and was originally claimed to be beyond the capacity of the WG to maintain long-term.

To address that, I suggest that you delegate the primary maintenance of the Open list to others who have shown interest, in particular @physikerwelt and myself. We can build a satisfactory UI (developing further the early 2022 ideas ) and proceed to engage our large communities of authors (in Wikipedia and arXiv) to contribute. Keeping the primary YAML file in this repository is fine, but we really need to do work on enabling the "Open contributions" aspect. The Open idea only works if we get a very diverse range of practitioners adding to the list.

Please lean on others and delegate. Don't (half-heartedly) encourage me to contribute - enable me to contribute. If I've shown that I can be productive anywhere, it has been this list. This request also means that I feel obstructed to be productive here today, and have for some time.

or some smaller group has write access and people submit PRs.

Every Math WG member is qualified to review and accept/reject PRs for the Open list in my mind, but we also need a person who can be a primary driver that will keep the project alive.

The stagnation has gone a bit too far, so opening a new issue to tackle that.

---

Technical UI proposal:

• aimed at non-programmer STEM authors
• offers a flexible spreadsheet view
• allows for easy search into the existing Open list
• guides contributors to add new concepts, explaining all metadata requirements in the secondary columns
• enforces a mini spec for writing notations and speech hints
• auto-links URLs to existing wikidata entries of a matching name
• auto-prepares PRs using the github credentials of the contributor
• visualizes open PRs as "pending" entries in the spreadsheet
• leaves room for implementing an aliasing solution Intent "alias" capability #40

A minimum sucess metric would be getting to at least 50 external contributors in 1 year after providing the UI to the public. I could attempt to build this by summer 2025.

[physikerwelt]

Many years ago, we implemented an approach that uses Github as data repository https://github.com/gipplab/MathMLben

We could also integrate something like that to our current MaRDI portal.

[davidcarlisle]

@dginev

I've contributed plenty to the Core list since, but zero contributions to this new Open list. That is a red flag - I suggest we start considering the current Open list experiment as a "collaborative failure" (one internal to the WG).

I would disagree. It is entirely expected and not related to the form or location of the open list.

The initial yaml was a merge or the original list collated by you and David farmer and others, and predated the current intent syntax. So it formed a major part in what is now core and there are some commits making that split, and then several commits tracing changes in intent syntax and changes in display format following Working group comments.

But open is essentially the list for contributing additional contributions that are not in core. I wouldn't expect anyone to make contributions while, as you note above, core is under active development.

I would see the major use of open as a shared list (under a clearly official w3c home) where different systems can share a common list of names. However even for MathCAT which is effectively the reference system, I wouldn't consider it useful to continuously track its internal concept list to a public open list while things are in development. Once MathML4 is published, I would expect that we would do that for MathCAT. Doing it now would be premature and just lead to churn.

It would be good if other mathematical speech engines would support intent and share a list of implemented concept names via the open list, but VoiceOver, SRE, MathCAT, ... The number of systems are going to be in single figures, so the number of teams making bulk PR to the open list is never going to be large and I would expect making a PR to a yaml file would be a lot more convenient than a custom web interface for editing individual entries.

That said, if we do expect entries from "end users" perhaps to log names they have used as unknown concepts in their document, then a different interface would certainly be possible. I would encourage you to make such an interface any names harvested there
can still be added to the yaml, so it is not an either-or situation.

As any system can have a list of concept names and can publish them, I think it's good to have the central open list under W3C banner. That does limit things. If you think a git PR to github is too technical and discouraging, the alternative would be tunnelling CVS commit through ssh to add to files on w3c.org, which I can promise you isn't any easier.

[physikerwelt]

@davidcarlisle I don‘t see any arguments against @dginev s proposal.

The goal is to get more pull requests.

[davidcarlisle]

@davidcarlisle I don‘t see any arguments against @dginev s proposal.

The goal is to get more pull requests.

That is not a goal, PR are are just a detail not a desired property.

PR are not expected at this time, As I mentioned, even for someone in the inner loop with something like mathcat's internal concept list, it would be premature to add them before intent is even officially standardised.

But as I replied above I've no objection to you hosting a front end similar to the site you linked to that takes individual contributions and (presumably) generates a PR to github. Personally I think it's highly unlikely to get many such individual edits. Updates to the open list will come if a new speech engine (apple voice over for example) supports intent and makes available its data as an open list.
Such updates would come as a bulk edits to the yaml data not via a friendly GUI.

Currently as recently as last week the working group meetings have been discussing adjusting the format, which is fine, that is why the spec is still in draft form, once we go to CR and REC the formats will need to be more stable and it would be more reasonable to expect contributions.

[dginev]

I honestly have no common basis with the comments @davidcarlisle is writing. I see the work on the Open list completely differently - and would be happy to lead it.

We can get external contributions from regular authors, resource admins, and AT developers, continuously - adapting to churn with light editorial work - and maintaining machine-readability of the Open list.

The spec being finalized or not is a red herring, as the exact list contents aren't the subject of the primary spec text. MathML 4 defines the intent syntax, and mentions the lists, but doesn't prescribe the inner workings of the Open List.

MathCAT is another red herring, the intention is to have loose coupling between AT systems and the Open list. Contributors should bring any concept which may benefit from dedicated AT support - they can do so without having any awareness of MathCAT as an individual system. The Open list should be a suggestion for an implementation target for ATs, and not something ATs exclusively control to synchronize coverage (what a grim idea!)

The tight-fisted vision David is proposing has no appeal for me, and I will do anything I can to see us correct course. If the WG decides to go with the stagnation plan, I'll invite everyone interested to develop a better resource externally to the WG, sad as that would be, and to treat the W3C Intent Open list as a born-deprecated resource.

[NSoiffer]

I see two different communities potentially contributing to the open list: authors/authoring software developers and AT developers. The first group is likely to contribute the most entries, but the later probably wants to "advertise" what it supports outside of core and that might be new entries in the open list.

I don't have any objections to contributing to the open list now, but it does seem premature to do so given that the core list hasn't been finalized. We did do a big pass to build up the current core list, but we also said we need to revisit that list, so it will likely change. Given that the spec for intent itself may change a little before CR, I am concerned about wasted effort having to go back and make changes to a large number of entries. But if you (Deyan) don't mind potentially having to change things, knock yourself out and work on a better submission system that encourages the community to make contributions. Just make it clear that FOR NOW, intents are a work in progress. The open list, by definition, will always be a work in progress but at least the foundation upon which it stands will eventually be a firm one. At the moment, it's a bit shaky.

[davidcarlisle]

There will likely to be lists elsewhere anyway, latex might document the intents it uses for example, so if you can make a nice gui that harnesses a lot of names that is all good. I do strongly suggest that the open list referenced from the spec is under the the w3c banner as that is what distinguishes it from other lists. But any list can be periodically pulled in to that central list so it's no barrier on you experimenting with alternative interfaces.

That would also isolate you from the current lack of specification of the format of the central yaml files you can then store the data however you like, and it can be converted as it is pulled in

[dginev]

I am just catching up on the comments here and am seeing more agreement towards an enhanced Web UI approach for Open, with clear messaging and expectations to remain flexible.

Does this need a group vote, or should I assume there is solid agreement that I can build a prototype and attempt to contribute it back by summer 2025? The UI implementation will likely add a couple of constraints on what is easy to specify for the Open columns, so if people have strong opinions on those, they may want to stay in close contact with me. I am hoping to coordinate more with @physikerwelt and to present checkpoint progress at WG meetings, as appropriate.

[davidcarlisle]

@dginev I think there is broad agreement that you and @physikerwelt should experiment with a UI for submissions. I don't think any WG vote is needed as such but if you would rather the work was backed by an explicit endorsement from the group I'd be happy to propose such a thing and we can vote on it.

As you indicated, the format of the yaml file with the data is under Working Group control but probably as you experiment with automated update possibilities you'll want to update (or constrain) that a bit, which won't be any surprise and can be handled by issues/PR in the normal way. Practically speaking current edits have all just been via generic yaml editing in an editor, and I think the only system reading the open.yaml currently is the github-pages display. So you should be able to suggest adjustments when needed without fear of breaking too much I think, just see how it goes.