Talk:VisualEditor/Design/Reference Dialog

Feedback for VisualEditor Reference Dialog

Please implement this idea
Trully amazing idea! It would be really easier and faster to add references this way. if implemented this is going to have a huge impact in long term, just keep going. Cheers from a ptwiki user. TheVulcan (talk) 02:06, 21 September 2013 (UTC)

Step 1
Step 1 can be eliminated by putting the Reference icon back on the main toolbar, rather than putting it under "More". Space can be made for the Reference icon, on the toolbar, by putting all text formatting options (bold, italic, strikethrough, superscript, subscript, computer code, etc.) under a "Format text" pull-down menu, which is more intuitive than the "More" label. See here for further discussion.

Step 2
The top-most heading ("Choose a template or enter manually"), is fine, but there then should be two parallel sections of the dialog box: "Choose a template" and "Enter reference manually". The first of these two ("Choose a template") is missing; instead, the top-most heading has been combined with the first option. The reader should be able to grasp, immediately, looking at the box, that - per the heading - he/she should use one of two subsections, and these two subsections should be separately boxed, with separate sub-headings.

There should be a minimum of blank lines (horizontal spacing) in the dialog box, so the user an quickly see what the two options are. (The version shown is hopefully just done quickly, rather than intended to show where text will actually appear.)

The sequence of templates will, hopefully, be controlled by individual projects. For example, at the English Wikipedia, Cite Web would probably be first, since it's most common.

The full name of templates should be shown ("Cite web", not "Web"). This is helpful for wikitext editors switching to VE, or VE editors who use the wikitext editor, but it's also helpful when doing a search - because the user now has a much better idea as to what other templates are likely to be named. If longer names don't fit into a five-wide list, then there is plenty of space to do a five-deep list instead. (Having the full name of the template show, in the dialog, rather than a portion of it, also means less translation work, since there wouldn't be a need for a label for each citation template.)

The number of "slots" for templates also should be project-controlled, perhaps with an upper limit of 10, rather than WMF deciding on behalf of the projects that five is the ideal number. If a five-deep list is used - see prior paragraph - then there could be a second column for templates six through ten.

There is no reason to have a "Next" button. When the user clicks on a specific template, that should invoke step 3. The user should not have to (a) select a template and then (b) click "Next". (If the "Next" button is related to the search box, it should be to the right of the search box, not below it, and it should have the search icon in it, or the word "Search", or similar. However, it's easier just to press [return], as is done, for example, in the search box at the upper right of MediaWiki pages, rather than click on a separate button to start a search.)

The words "Search more templates" should be "Find more templates".

Overall comments on steps 3 through 5
Arguably, the correct approach to adding references is to improve the template dialog so that steps 3 through 5 would be done inside that dialog, not as part of a different dialog, with a different user interface. (Or, roughly equivalently, if the reference dialog used, as a base, the template dialog code when performing steps 3 through 5.) It's true that cite templates are different than (almost?) all other templates because of autofill possibilities, but that's a relatively minor difference that could easily be factored onto the standard template dialog.

It's true that the template dialog is desperately in need of redesign, and, arguably, the reference dialog is a priority. But screens 3 through 5 are not consistent with how the template dialog is currently designed (specifically, the left side of the dialog box showing parameters selected, the right side used to select additional parameters, and to fill in parameter values), a design I believe is fundamentally correct. So the approach in these design specifications for the reference dialog - assuming the template dialog stays approximately as is - will result in users having to learn two different systems for templates - one for citation templates, and one for other types of templates. That's almost certainly a mistake.

Step 3 (3a)
The heading should be "Cite book" (the name of the template), not "Book". [And similar for subsequent screens.]

It is not at all clear that the user should press [return] after entering an ISBN, in order to invoke the autofill option. (That is, to enter a value and then do a search - why search if he/she knows the ISBN?) Rather, there is a good chance that the user will type the ISBN, then tab to the next field, enter that information, tab to the next field, etc.

What should be done is to have a button, immediately below the ISBN, labelled "Autofill other parameters". That's something that an editor obviously would want to click on. If the autofill fails, a message should be displayed below it (so there should be blank space on the screen for such a message): "Unable to autofill; ISBN may be incorrect or autofill function may not be working"). In the case of such an error message, the user should not need to acknowledge the message (click on anything, an extra step) but can simply start manually entering information.

Having a separate button is also desirable because there will certainly be cases where no autofill option is available. In such cases, the lack of an autofill button will clearly indicate to the user that he/she is going to have to manually fill in parameter fields.

The list of parameters doesn't group them by "required" versus "optional" - at least, it's not clear that it does, and the description of the dialog doesn't mention this point. (As may be obvious, but just in case: For each parameter, the TemplateData information in the template states whether the parameter is required or not.) If both required and optional parameters are in the scrollable list, there should be a heading "Required parameters", then a list of required parameters, followed by the heading "Optional parameters", and a list of those. (There could be either a single scrollable list, or two scrollable lists, if space permits). Parameters not specified as having one of these two values should be considered "Optional".


 * Alternatively, only "Required" parameters might be listed. That appears to be the case, looking at the "Adding Parameters" screen. If so, the developer description of the dialog should be modified to state that this is the approach being taken.

The first parameter shown (ISBN) has the description information from the TemplateData documentation for the template, which is excellent. But the other parameters should also have their descriptions. Thus, for example, "Last name" should have, directly under the space for entering that parameter, this description: "The surname of the editor; don't wikilink, use 'editor-link'; can suffix with a numeral to add additional editors". (I don't happen to think this is the best description, but WMF shouldn't worry about that - the projects will have a real incentive to improve descriptions that appear in the dialog.) (Oddly enough, in the screen showing for step 5 ("Additional Parameters"), a description for the parameter "Place" is visible, but the text is not taken from TemplateData.)

The "Result" field shows six items ("Last name, First name, ..."). In fact, there are eight required parameters for Cite book - the missing two are Publisher and Pages. Presumably the "Results" field should show all required paramters, not a subset, and this is just an oversight; if not, the developer description of the dialog should be modified to explain why not all parameters are included in this box.


 * Note: Regarding the ''Results" field, for additional comments, see step 4, below.

Step 3b
It's unclear why the "Results" field doesn't show the same thing as in Step 3a, and why that field is no longer greyed out after the ISBN has been entered. Does entering even one character in a field activate the "Results" box? (If so, why?)

Step 4
The current dialog description doesn't cover the situation - as is the case with Cite book - where a parameter is required (in this case, "Pages") but is not autofilled. Nor does it cover the case where, for some reason, autofill can't fill all the fields that it normally does - for example, say, the publisher location is unavailable from the database used for autofill.


 * Recommendation: where one or more required fields is still blank following autofill, the dialog box should scroll the parameter window so that the first blank (and required) parameter in that window is visible, along with its description.


 * It would be extremely helpful if a message were displayed, near the top of the dialog box, something like "7 of 8 required parameters have been filled in". That would encourage editors to complete all required parameters. [This wouldn't be a clickable/closeable message, but rather text placed in previously blank space.]

The statement "The user may also edit the reference here [in the Result box] if they wish" needs further explanation. If the user is now able to do free-form editing, this potentially breaks the template. If editing in this box results in the equivalent of doing an "Enter reference manually" (step 1) - that is, if the wikitext added to the page becomes rather than, this is extremely undesirable. It's extremely undesirable because preserving parameters makes it possible for bots, now or in the future, to work with structured data, but that data must be inside a template.


 * The alternative is to make the Result box consist of fields (ideally, with small labels) for each parameter. Then while the editor might edit a field, the structure (that is, the template) is preserved. Alternatively, if the Results box contains fields, then clicking on one could take the user to that parameter, in the scrolling list, where he/she can make any desired change.

Once at least one parameter has been added, clicking on "Back to templates" should cause a pop-up dialog box: "Are you sure you want to return to discard the information you have entered, and return to templates? [yes] [no]"

Adding parameters (optional step 5)
"The option to add more parameters from a template is visible after the user scrolls to the bottom of the form" is far from a complete description of how this functionality works. And the drop-down menu near the bottom of the "Adding parameters" screen looks very different than how one adds a parameter in the current template dialog, where the user can find a parameter by scrolling or by searching. Is there some reason not to use the (better) "add parameter" functionality of the current template dialog?

Comments on "Notes"
Regarding this:


 * "This design iteration does not include the "Use this group" feature. However, in the future a user may be able to organize groups of references within the article."

While it's fine (in my opinion) to delay this functionality, it would be highly desirable to put a placeholder into the dialog box so that users understand that (a) references added via this dialog will automatically go into the standard/default group, and (b) that in the future, they will have the ability to change this.

Specifically, it would be desirable to put this to the right of "Book" (or, as suggested above, "Cite book", on screens three through 5:


 * Group: [Standard] VisualEditor - Icon - Down.svg  [New]

Where ["Standard"] (or "Default") is a field with a drop-down arrow that is greyed out, and "[New]" is an button that is greyed out. Eventually a user could use the down-arrow to select an existing group, other than standard/default, and could click on "[New]" to create a new group.


 * The programming work here should be minimal - the "Group" field should already exist, and the "New" button would be non-functional.

John Broughton (talk) 03:35, 21 September 2013 (UTC)

I don't understand Design Iteration 1
In the Design Iteration 1 it describes entering a citation template into the reference (at English Wikipedia what we are calling reference in this case would normally be called a footnote or endnote elsewhere; the reference dialogue edits the entire "reference", which may include just a citation, or may a citation and some prose, or even a long multiple-paragraph, formatted appendix-like piece of prose with blockquotes etc). But how does an editor edit the rest of the reference, for example, if she wants to include an explanatory note along with the template citation? The example is not clear how this would be done.

Also, the template editor as it is still uses wikitext for extra formatting when the editor wants it, is that still going to be the case here for these citation templates? --Atethnekos (talk) 04:27, 21 September 2013 (UTC)


 * Good point. I suggest adding another, final field, "Additional information", with a parenthetical "(optional)" as part of the label. This would be placed below the "Results" box/field, and which would (ideally) accept wikitext, not just plain text. And the larger point is also relevant - the interface for reference/cite templates should be similar to that for other templates, to minimize user learning. John Broughton (talk) 18:10, 21 September 2013 (UTC)

My dad might get frightened.
Step 1 also need to show a use existing reference option.

Some cite templates can have a very large number of parameters. I think its it the region of 200, with first and last names for 9 authors and editors see en:Template:Cite_journal/doc which is still missing some. This could make for a long scroll list.

might be import for this as it discusses a recommended option for parameters in TemplateData, used to give a hint as to which parameters to show to start with.

Are all parameters going to me in the list. Having to search would be tricky as if you don't know the template you don't know what to search for. Would you guess there is an parameter in en:Template:Cite journal.

Some beginning users just like to paste a bare URL or just type an unformatted reference. These are both better than no reference at all. My elderly dad tried adding a reference to an article and it was too complicated for him to fill in all the parameters. I can see him worrying about having and ISBN box to fill in for a book published in the 19th century. What should he put in the field, is it OK to leave it empty. The barrier to entry must be very low.--Salix alba (talk) 17:57, 21 September 2013 (UTC)


 * With regard to the first point, yes, Screen 1 should present three parallel options: Use a template for a new reference; Enter a reference manually; or Use an existing reference. It's not clear why the third option, which is now in the Reference dialog, was omitted.


 * With regard to the large number of parameters, it looks like the list presented to users will include only parameters that are specified as 'required in a template's TemplateData section. (With regard to "Recommended" parameters, it doesn't look like that suggestion has got much traction. But after this redesign, there might well be a demand for a categorization other than "required" and "optional".


 * For users who want to just type an unformatted reference, Screen 1 has an "Enter reference manually" field/box. I've suggested making it more clear that this option is parallel to selecting a template (and, as someone else has pointed out, to using an existing reference). But arguably the manual option should be listed first, so that absolute novices can just post a url and be done with the matter.


 * And I wouldn't expect novices to search for a template that they're unfamiliar with; the search is there for expert editors who use a citation template that isn't on the standard list. John Broughton (talk) 18:23, 21 September 2013 (UTC)