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)


 * This of course is the other point. Look at the users and think about them. Look at the folks we meet at training courses. Salix alba dad is an important starting point. Wise, knowledgeable, a history of publications behind him having no history of wikipedia jargon. He knows this occurs in Kernigan and Ritchie- because that is part of his DNA probably around page 80.
 * Page one uses the term template, enter a reference manually this is jargon- it needs to be in the users language

pet hate transclusion.
 * ISBNs are relatively modern- an academic will rely on books like Naismith (1896) and later editions, The Students' Cotton Spinning. A lot of editing is needed converting 10 digit to 13 digit and (10and 13 digit) to just 13 digit. It the interface can just make it clear, that a ISBN if entered will help by filling in some of the details
 * Large number of books have multiple authors, any template needs to assume this. We also have the JRRowlings problem, just how do you enter initials instead of a first name.
 * In normal referencing you use sfn and efn referring to a Bibliography section. Often we don't need the user to add a full cite, just (Last,Last2, year, page) I don't see how this is done here.
 * How is this template used to correct an existing reference.
 * I'll point out that this really isn't necessary at all because when we write a visual editor, referencing will occur in line, the mode changing when the user presses a Function Key, or the software will auto-magically detect it is a reference and help the user format it correctly. Roll on the twenty-first century! --ClemRutter (talk) 09:21, 22 September 2013 (UTC)


 * Regarding "The mode changing when the user presses a Function Key", this seems little different from "The Reference dialog opening when the user clicks the Reference icon."


 * Regarding "Jargon", two comments. First, why don't you suggest alternative language? Second, I think it's appropriate to expect a user to experiment a little. If a user sees "Book" (I prefer "Cite book") as a link that can be clicked, it's appropriate to expect them to try the link to see what happens. What isn't appropriate is (a) penalizing the user for trying a link, say, by making it difficult to go back to familiar ground - which we don't, here, or (b) dumping the user into a confusing place, which again I think we don't, here - at least we don't based on the changes I suggested, above. For example, clicking on "Book" (or "Cite book") takes the user to a screen where he/she can add an ISBN and click "Auto fill other parameters". That's pretty straightforward; there is a clear "Back to templates" option.


 * More than 90 percent of book cites in Wikipedia, I'm sure, are of books that do have ISBNs. Thus I don't understand why you emphasize older books as if they were critically important. Moreover, entering an ISBN isn't mandatory in the dialog box for the cite book template, as you seem to think.


 * Your point about multiple authors is a good one; for the cite template, there probably should be a pull-down menu to specify how many authors there are, and the parameters should change accordingly. However, this isn't trivial to program, particularly since it could easily vary across different language Wikipedias. Better yet would be to have the ISBN lookup understand how to handle a book with multiple authors, and to do an autofill accordingly.


 * Regarding initials versus "First name", my comments (above) recommend that TemplateData descriptions be displayed below all parameters (in the mockups, they show only for some parameters). The description for first name can say (for all I know, actually does) how to handle initials. So this isn't something to code into the template.


 * Eventually the reference dialog should handle both plain references and two-step references (Chicago and Harvard style; "References" only versus both "Notes" and "References" sections), but initially the dialog should handle the most common case, which is plain references (one step). We need to walk before we try to run.


 * Regarding 13-digit ISBNs versus 10-digit ISBNs, the description (text) under the ISBN field says to use 13-digit ISBNs "where possible". I don't know if the autofill tool works with 10-digit ISBNs (or how frequently), but again that's wording that can be tweaked in the TemplateData section of a template, to strike the right balance regarding how much we want people to look for a 13-digit ISBN (say, via an Amazon book lookup.)


 * As for editing an existing reference, the starting process is different (select the reference, then click the Reference icon, per the User guide. If the reference was created "manually", it can then be edited directly; if it was created by a template, clicking on the text of the reference opens the Template dialog. I don't see that this approach needs to change; it seems consistent with the proposed redesign of the dialog for creating a new reference. John Broughton (talk) 21:30, 22 September 2013 (UTC)

John, as there only seem to be two of here in this section- I will quote you and put a clarification/comment after each section


 * Regarding "The mode changing when the user presses a Function Key", this seems little different from "The Reference dialog opening when the user clicks the Reference icon."To a more keyboard savvy elderly user- Function keys are easily, as the hands don't leave the keyboard and you don't have to hunt the screen for an icon (visually difficult for bifocal users). The use of a separate data-entry window rather than entering the data inline breaks the intellectual focus on the text- surely this is the aim of a VE. I see it that the reference is typed in line but the area of focus is displayed in a different colour- with hints as to the possible fields. VE has a large number of function keys already, adding one more to invoke the Reference dialog isn't that big a deal. However, it's problematical to find just a two-key combination, and using a three-key combination to invoke something isn't exactly trivial. As for entering the data inline, you're absolutely wrong that this is possible. A dialog box is needed, for example, to ask the user if he/she wants to (a) use a form/template/framework, and if so, which one; or (b) just type in the reference information, or (c) use an existing reference. And no, it's not possible for the computer (VE software) to just let the user start typing away, and figure out from that what the user wants. So staying inline, when entering reference information, isn't a realistic option.


 *  Regarding "Jargon", two comments. First, why don't you suggest alternative language? Second, I think it's appropriate to expect a user to experiment a little. If a user sees "Book" (I prefer "Cite book") as a link that can be clicked, it's appropriate to expect them to try the link to see what happens. What isn't appropriate is (a) penalizing the user for trying a link, say, by making it difficult to go back to familiar ground - which we don't, here, or (b) dumping the user into a confusing place, which again I think we don't, here - at least we don't based on the changes I suggested, above. For example, clicking on "Book" (or "Cite book") takes the user to a screen where he/she can add an ISBN and click "Auto fill other parameters". That's pretty straightforward; there is a clear "Back to templates" option. Alternative wording will vary in each language but it is really the difference between programmer focussed language, and user focussed language. There is tons of literature on the hazards of predicting user acceptable language- but we must try. Take the example of a teaching a session to a Local History Society with an average age of 395. We want you to say where we can verify the information you have just provided- we have two concepts in play. Information and a citation- lets not cloud the issue by starting to define IT terms. The task we are talking about is Adding a Reference- add that to the heading. Ask them 'would you like to type the reference in directly, or use one of the help frameworks below'. So I guess in English I would call it a Help framework, or formatting framework- though that reeks of jargon. I wouldn't try to teach, for example, auto mechanics without using "jargon", and I don't think Wikipedia can be taught without asking users to learn some new words ("jargon") and concepts. I'll repeat that I think it's reasonable to expect users to do a little experimentation; if they won't, then, quite frankly, I don't think they have what it takes to be a successful Wikipedia editor.


 *  More than 90 percent of book cites in Wikipedia, I'm sure, are of books that do have ISBNs. Thus I don't understand why you emphasize older books as if they were critically important. Moreover, entering an ISBN isn't mandatory in the dialog box for the cite book template, as you seem to think. Why older books- because I am playing devils advocate and many of the books provided for the sessions I am imagining are older books. I don't work a lot in the Triviapedia field- popstars and soap operas don't enter my wikiworld. ISBNs (10 digit) have existed since 1970. There are a lot of non-Trivipedia books that have been published since 1970. And I repeat: the ISBN is not mandatory, it's just a way to avoid typing lots of other information.


 *  Your point about multiple authors is a good one; for the cite template, there probably should be a pull-down menu to specify how many authors there are, and the parameters should change accordingly. However, this isn't trivial to program, particularly since it could easily vary across different language Wikipedias. Better yet would be to have the ISBN lookup understand how to handle a book with multiple authors, and to do an autofill accordingly. Cheers.


 *  Regarding initials versus "First name", my comments (above) recommend that TemplateData descriptions be displayed below all parameters (in the mockups, they show only for some parameters). The description for first name can say (for all I know, actually does) how to handle initials. So this isn't something to code into the template. Not the citation, but in the data entry template it would be helpful to say what to do, or leave it as an alternative box. I am still thinking of my Local History Society session- and the questions they will ask. We seem to be talking past each other. Every field in which data can be entered, in the template, should be accompanied by its TemplateData description, just below. That description should "say what to do".


 *  Eventually the reference dialog should handle both plain references and two-step references (Chicago and Harvard style; "References" only versus both "Notes" and "References" sections), but initially the dialog should handle the most common case, which is plain references (one step). We need to walk before we try to run. Absolutely, from a management point of view, but from a teaching point of view "Notes" and "References" is far more useful. sfn and efn are a god send. If we have someone writing about eighteen century history, it is unlike they will have more than one source book from which they will want to put four or so references into the text they have written. Seriously, do we want them to write the same 13 digit number 4 times, before they can add the page number. Can we take a different approach and provide a Short reference option- to give the sfn template. On Save/Apply- the server identifys whether this reference (on one very close) is in the Bibliography section. If yes, it saves if not, it falls back to the cite book template, autofilling a few fields- and offering the isbn box.. etc On Save/Apply they will obviously be a little housekeeping done to set up the necessary text. It will then be trivial to allow efns and Footnote facilities. No, they don't need to enter the same 13 digit number 4 times. The first screen of the Reference dialog is where users are given the opportunity to reuse an existing citation. What we should do is, when a user reuses an existing reference, is to allow him/her to specify the page number in a separate field.


 *  Regarding 13-digit ISBNs versus 10-digit ISBNs, the description (text) under the ISBN field says to use 13-digit ISBNs "where possible". I don't know if the autofill tool works with 10-digit ISBNs (or how frequently), but again that's wording that can be tweaked in the TemplateData section of a template, to strike the right balance regarding how much we want people to look for a 13-digit ISBN (say, via an Amazon book lookup.) A little post processing to remove the 10 digit code would probably fix it.


 *  As for editing an existing reference, the starting process is different (select the reference, then click the Reference icon, per the User guide. If the reference was created "manually", it can then be edited directly; if it was created by a template, clicking on the text of the reference opens the Template dialog. I don't see that this approach needs to change; it seems consistent with the proposed redesign of the dialog for creating a new reference. Fine, I was concerned that one of the class would want to make a correction. There is always the problem of someone citing the first edition, while taking page numbers from the second.


 * I hope that helps.--ClemRutter (talk) 22:56, 22 September 2013 (UTC)


 * I've added further comments with underlining, above. John Broughton (talk) 03:08, 24 September 2013 (UTC)