Adam Cuerdon comments:

I'd suggest popping up a note telling the user what he or she is doing at least the first time, though. Something like "This reference is used to document the source of text in the article. You can also edit it by clicking on the number after the text. Please make sure that you don't accidentally break documentation with your edit. Thanks for your work!"
We don't want to have a situation where newbies, for example, try to alphabetise the list, say.

Personally, I'm not sure "documentation" is the right word, but otherwise it seems like a good suggestion.

The alphabetising problem could perhaps be reduced by making the references only limitedly editable. i.e. Only individually editable in a dialog that allows for the editing of the template/parameters only.

New feedback from a user (a beginner) who wants to change a reference rom the reflist while editing with VE.

Copying my comment in from the other ticket, since I think it remains relevant here:

The major hangup on this is that it's going to expose the challenges with VE seeing references that're defined within templates. (Because of the current lack of a centralized way to edit references, this is only really visible to users from the "reuse citation" part of the cite dialog, where such references don't appear.) I suspect that if we accept having those ones greyed out in the list with a "this can't be edited here" tooltip, the rest of this should be fairly simple to do -- unless I'm not thinking of something, it's "just" hooking up a few bits of already-existing functionality and doing some UI work to expose them.

Following on from David's point, there are two ways the the reference list is rendered in the VisualEditor surface:

1. Using the HTML of the ref list supplied by Parsoid: This will include all references, included those defined inside templates (e.g. infoboxes), but the numbers will not necessarily map to those in VE's data model, so mapping from these references to editable references will be hard.
2. Generating a reference list by iterating over references in the document model: This will exclude references defined inside templates, but can easily be mapped back to the reference data in VE's data model. This list could be edited directly, or be used to launch a reference editor relatively easily.

(1) is used on the first load mostly for performance reasons (implemented in https://gerrit.wikimedia.org/r/c/mediawiki/extensions/Cite/+/411101) as it's a lot quicker to use the pre-generated HTML; rebuilding the reference list can be pretty slow on large pages. It also helps on wikis where most references are defined in templates, such as he.wiki.

Even if we switch to just using (2) this will mean that references are re-numbered when switching from read mode to edit mode.

From a UI perspective, we will need a way of showing the reference list context, probably by not embedding it but also thinking about where a user can click to show it (as clicking the reference list contents would now let you edit the list in some way)

I was thinking that a quick path forward would be for the reference list to offer a button that opened up a variant on the reuse dialog. In its context item would be the easiest place.

Even if we switch to just using (2) this will mean that references are re-numbered when switching from read mode to edit mode.

I think we're stuck with the references renumbering in the reflist if the user edits any of them anyway, so it might be better to do it up-front and have them stay consistent throughout the entire session.

In T54750#8641368, @DLynch wrote:

Even if we switch to just using (2) this will mean that references are re-numbered when switching from read mode to edit mode.

I think we're stuck with the references renumbering in the reflist if the user edits any of them anyway, so it might be better to do it up-front and have them stay consistent throughout the entire session.

It takes ~800ms to render the list on [[Barack Obama]], hence not doing it up-front. Also on he.wiki, the initial rendering is the only rendering with content.