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)
 * Nothing much to add myself just yet, other than I agree! I wasn't aware until yesterday that there was going to be any reference-dialogue action other than a blank freetext field. The absence of a simple but powerful footnote-creator is my main (only?) reason for not using VisualEditor for my day-to-day editing, so I'm very pleased to see this is on the cards. Could you please reiterate in your future newsletters/announcements that this sub-section of the visual editor project is actively being worked on as I'm sure there's a lot of people out there who (like me) don't know about it but are very interested in supporting it. Wittylama (talk) 02:26, 30 January 2014 (UTC)
 * I'll make a note to highlight it in the next newsletter (it's been linked in the last handful), although response from such requests has been very limited, so I don't think you should count on much. What seems to produce feedback is not requests, but putting a design into VisualEditor and waiting for "spontaneous feedback" (usually in the form of loud complaints).  Whatamidoing (WMF) (talk) 00:04, 31 January 2014 (UTC)
 * No, what produces results is going to the VE feedback page and asking for feedback. You didn't get any response about the character inserter even after you had put it into production, because no one who really uses VE uses the advanced options (much too likely to cause issues, and much too advanced for the few users that use VE in general). You got a response at the English wikipedia because you finally asked at the right place instead of in more general newsletters which aren't apparently read by the few VE editors or testers you have left (in my case, they are ignored because they are unreliable and even errors that are pointed out upfront don't get corrected).
 * So why not try a new approach? Come to the VE feedback page on en-wiki (and other wikis of your liking), and announce that some new tool is available on Mediawiki, and that before you release it to the world (and loud complaints), you would like some feedback on it.
 * Better yet: why not use a completely different approach to developing software?


 * Get feedback from editors as to what they would like to have
 * Look at what already exists in the normal wikitext environment (standard and oft-used gadgets)
 * Analyse, develop, improve
 * Get your QA team to test it and give their feedback
 * Go back to the editors who provided the initial feedback and ask them to test it and give their opinion
 * Eat, sleep, repeat
 * And then, and only then, introduce it to the other wikis
 * It would reduce the chance of further utter failures like the character insertor (or the VE implementation as a whole), and the accompanying number of "loud complaints". Fram (talk) 09:12, 31 January 2014 (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]"


 * The proposed display for this step only gives the values of the parameters (e.g. "Horuki") not the name of the parameter (e.g. "first1"). This makes it difficult to properly inspect the citation to see if the search process properly classified the words that were found (Maybe Horuki was really a translator or editor, not an author). Jc3s5h (talk) 17:37, 22 October 2013 (UTC)

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. Auto mechanics to a night school class of ladies you do remove all the jargon until they are comfortable with the concepts- and then you do at their prompting, introduce some technical terms. Yes I did help write some course material in the 1970s. But that's an aside, you work with the volunteers coming forward not the ideal student. Yes encourage them to speculate and experiment- and they will discover that wikicode is more powerful and faster to write- but if they are starting out we need to encourage each one. Yes, most won't ever become successful and dedicated WP editors.
 *  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. True true and true- but lets remember the others


 *  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". Perfect


 *  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. Good- ideally this template should suit, the referencer volunteer, who is using a one notable book to reference un-cited text in a string of similar articles 


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


 * Much appreciated- and few responses. --ClemRutter (talk) 23:00, 28 September 2013 (UTC)

Nested templates
This design iteration does not allow for templates within templates.

If you don't support the inclusion of templates within templates, then you cannot add a dead link template inside the reference to mark a dead URL, like this:

Does it support adding the template after the citation template? That wouldn't be perfect, but it might be good enough.

What's going to happen if someone tries to edit a template that contains a deadlink template? Whatamidoing (WMF) (talk) 17:39, 30 September 2013 (UTC)


 * The transclusion dialog supports (only) wikitext for the parameters of a template, so if you were adding the "Cite web" template, you'd just type in  from your example and it would work as expected (but it's not at all discoverable and is a bad user experience). Jdforrester (WMF) (talk) 01:54, 1 October 2013 (UTC)

Reference icon
The goal for the reference icon is something that anybody (in any language or culture) can look at and think "Here's how to put a reference on the page!"

The book/bookmark icon does not seem to be ideal in this regard. One suggestion has been to use the little blue numbers: as part of an icon, although we'd probably want it in black and white to avoid the fruit salad effect, and it would need to be adapted for different languages.

Does anyone have any other suggestions? Whatamidoing (WMF) (talk) 18:19, 30 September 2013 (UTC)


 * (You might want to see the discussion at en:Wikipedia:VisualEditor/Feedback/Toolbar if you're interested in this subject and haven't seen it before.) Whatamidoing (WMF) (talk) 18:35, 30 September 2013 (UTC)

Autofill
Is the ISBN autofill going to be a backend service hosted by Wikimedia Foundation? Will autofill also support journal DOIs? John Vandenberg (talk) 05:50, 2 October 2013 (UTC)


 * Yes. We need to investigate where we can get the data from, though.
 * That's the plan.
 * Jdforrester (WMF) (talk) 18:39, 2 October 2013 (UTC)
 * That's great news! ISBN autofill will be very cool. --Vojtech.dostal (talk) 20:27, 2 October 2013 (UTC)
 * WorldCat or OpenLibrary should be usable, though both have some issues with non-unique records for ISBNs. LeadSongDog (talk) 22:14, 31 October 2013 (UTC)

French Wikipedia references namespace
Does the WMF intend to support the French Wikipedia's dedicated references namespace 'w:fr:Aide:Espace référence'? e.g. w:fr:Spécial:Pages_liées/Référence:The_Disney_Middle_Ages_(Tison_Pugh_and_Susan_Aronstein). John Vandenberg (talk) 23:29, 2 October 2013 (UTC)
 * Wiktionary has a similar "Citations:" namespace, so it is not unique to fr.wp. I would be really surprised if they refused to support it, but I haven't heard anything about it (which probably means that it's not on the list for the next month or two).  Have you filed a bug report on it yet?  Whatamidoing (WMF) (talk) 16:06, 8 October 2013 (UTC)

My observation from trainings
Hi. I would decrease number of steps to max 2. If you cannot, please use Step 1/4, 2/4,... so that user knows, how much of all steps is it there. But if UI is flexible enough, I would go to only 2 steps: Wizard is good fo non-repeating task. But citing references is regular task and moving furth and back through wizard can be much time consuming and confusing.
 * 1) Selecting reference source
 * 2) immediately after selecting source, screen changes (without next) to table: Parameter / Entry or dropdown field.

Also, auto fill should be combined with dropdown, since some users surely don't know what to start typing and prefer drop-downs.

Again, I am not programmer and I don't know how UI technology is limited or not. Brg --ModriDirkac (talk) 09:11, 11 October 2013 (UTC)

not completely on topic - but
I just wanted to remind the developers that some of us still prefer to format citations and references the old fashioned way: by manually formatting with I often need to create somewhat complex citations, and find that these don't work when you use Visual Editor or other citation templates. I don't object to VE as a concept... but please make sure that not using it remains an option. Blueboar (talk) 18:57, 17 October 2013 (UTC)


 * What do you mean by "these don't work when you use Visual Editor"? Right now VisualEditor is completely built around inserting full references (rather than a simplified interface just for a few citation templates, which this discussion is about), and lets you insert anything you like into the reference. Is this not working for you somehow? Jdforrester (WMF) (talk) 19:12, 17 October 2013 (UTC)


 * Actually, my issue is more with citation templates in general than it is with VE specifically. I have found that on several occasions the various fields and prompts I was presented with in a template didn't actually fit what I was trying to cite.  It was easier and much quicker for me just to create it manually, without having figure out how to manipulate the template into giving me the presentation I wanted. I want to make sure that the option to do things the old way remains available to us. Blueboar (talk) 01:28, 18 October 2013 (UTC)


 * Oh, completely agreed that the templates aren't right for all uses and we should always ensure that people can write general content (rather than just a few templates) in references if they want to, easily and quickly, without adding confusion to users who won't know what to do if just presented with an empty editor box. If you look at the wireframes for iteration 2 of the design proposal (e.g. here), the "advanced dialog" would be a full empty editor in which you can put anything you like except sub-references - text, arbitrary templates, images, lists, tables, whatever is needed). We've also considered adding some quicker ways to get there than triggering a wizard and clicking advanced, possibly with a sub-menu in the reference insertion button - hopefully we can get a prototype thrown together pretty quickly to show off some possibilities soon. Jdforrester (WMF) (talk) 01:44, 18 October 2013 (UTC)


 * Because of a post from WhatamIdoing on WT:V on en.wiki, I just wanted to agree with Blueboar that it's very important to make sure the Visual Editor doesn't break the text interface in this or any other respect.S Marshall (talk) 23:52, 17 October 2013 (UTC)


 * When you say "break the text interface", do you mean the wikitext editor? We've no plans to put any of the VisualEditor tools into the wikitext editor yet (though it might be worthwhile to explore doing something in this area at some point). If you meant something else, please explain! Jdforrester (WMF) (talk) 00:02, 18 October 2013 (UTC)

Design iteration 2
When was iteration 2 created? I'd like to know what comments posted to this page refer to the previous iterations, and which ones are answers to Design 2. Diego Moya (talk) 19:23, 17 October 2013 (UTC)


 * : 2 October. Jdforrester (WMF) (talk) 19:59, 17 October 2013 (UTC)

Some feedback
I've been informally polling some of the content editors on English about what they'd like to see supported by the VE Ref Dialog. Some interesting points to consider: Anyways, just a few points - Design Iteration 2 looks great! PEarley (WMF) (talk) 20:15, 20 October 2013 (UTC)
 * Prompt for Reflist template: A good portion of our articles (and all our new articles) don't have the Reflist template in place. Currently, if you add ref tags in the wikitext editor when Reflist isn't there, you get that lovely red text at the bottom of the page. Having VE search for Reflist, and, if not found, prompting the editor to add it, would be a nice addition, and very helpful to new editors.
 * Support for "Footnote" style cite templates. The Harv and Sfn cite templates are popular in our Good and Featured Articles.  They also provide the only practical and accurate way to cite multiple pages/page ranges within the same work for multiple citations. These templates will probably also need a pop-up prompt to remind editors, and educate new editors, that they need a complementary citation template to be in place in the references section for the note to work properly.  While I agree with John above that this is advanced citation skillz here, and that we should focus on simple refs first, I think it's a good idea to have note-style refs in mind when designing.  Newer editors will look to our best content to see what to emulate, and many will want the notes functionality. (A new editor coming from an academic background especially will be wanting to make these type of cites)
 * Have two sets of parameters for common cite templates, the "recommended" elements, and the full list. Salix alba mentions this above, templates like "Cite journal" have dozens of possible fields - seeing them all at once would scare off the rookie editor, as well as slow down the veteran. I think that's how we have it in the mockup right now - the book example has only the commonly used elements (though it should probably should include "page number" in there too.) I think Iteration number 2 handles this nicely.


 * I don't think that you'd want to search for the reflist template, because that's not used everywhere (and where it is used, the template name often changes). But if you could find out whether the  scheme was chosen because (1) those buttons are available on almost every computer keyboard, not just the English/Latin script ones, and (2) it was extremely unlikely that it would conflict with any ref naming scheme chosen by a human.  I would also like to see meaningful names given.  Whatamidoing (WMF) (talk) 19:55, 6 November 2013 (UTC)

Modifying existing references
A user on English language Wikipedia who has been doing a lot of testing notes that correcting existing references may be an impenetrable process for new editors. Expecting to find the reference text in the reference section, they will find only the references template, and they will not see the text visibly displayed anywhere higher in the article. If they use "edit source", even if they are surprised by what they find under "references" they have the potential to find the text higher in the article. Unsure if there's anything that can be done to make this easier in future editions, but it's a fair point and so bringing it up. :) --Mdennis (WMF) (talk) 13:55, 5 November 2013 (UTC)

== Prompt for }}

which produces:

The Sun is pretty big. But the Moon is not so big. The Sun is also quite hot.
 * Notes

The cite-templates are pretty huge and it irks experienced editors when VE-user make the wikitext unreadable. What do you think? --Atlasowa (talk) 18:10, 19 November 2013 (UTC)


 * Bug 50110 - VisualEditor: Provide way for local wikis to auto-prompt reference templates seems related. --Atlasowa (talk) 11:54, 4 January 2014 (UTC)

Do you work on this?
Hello, I was promised the reference dialog on VE to be deployed in December 2013. Nothing has changed until now, is anyone at least working on this? It is very irresponsible to those who devote their time eg. to working with students, it is impossible to teach them VE if you don't follow the schedule :-(. This literally makes me very unhappy. --Vojtech.dostal (talk) 20:52, 16 February 2014 (UTC)
 * Hello Vojtech. Very sorry I didn't update you about the Reference dialog progress.  We are hoping to have a working version very soon.  It has proven more difficult than we expected, but we are close.  I will make sure to notify you (and the rest of the Czech editors) when we have a released version. PEarley (WMF) (talk) 00:57, 18 February 2014 (UTC)


 * What exactly is the status and the roadmap for the VE Reference dialog? VE Reference dialog is unchanged on VE on enWP (beta opt-in only) and VE on test2wiki and VE on frWP (live default for IPs). BTW, apparently the spanish WP has just cut off VE default for IPs on february 13?
 * I see very promising new VE Reference dialog mockups:


 * I love the URL autofill! And ISBN autofill! And googlebooks autofill! (See also en:Wikipedia:VisualEditor/Feedback/Archive_2014_1 with some stats about references.) It's gonna be great!
 * Wikipedians use a lot of tools to insert references, the VE team doesn't need to reinvent the wheel, but to build on earlier experiences with UI design too. Please don't say that you will notify Wikipedia editors only "when you have a released version".
 * Where can i test this? --Atlasowa (talk) 12:32, 19 February 2014 (UTC)
 * Hi Atlasowa,
 * We can't test it until they have some more-or-less working code. (I want PMID autofill.)  The critically important ISBN autofill, in particular, seems to be complicated by the diversity of databases, some of which seem to only cover certain country's or language's books.  Right now, I can't get a useful estimate from them about we'll actually see it ("not very soon" and "it depends" don't count).   Whatamidoing (WMF) (talk) 18:05, 19 February 2014 (UTC)


 * ISBN2Wiki (Magnus Manske) "You can enter an ISBN ... This script currently searches the following databases : Google books, DDB, Amazon, Biblio, Campusi, Library of Congress, WorldCat (deactivated : BOL, Buchkatalog, Froogle, ISBNDB)
 * Wikipedia template filling (Diberri?) "Enter a DrugBank ID, HGNC ID, ISBN, PubMed ID, PubMed Central ID, PubChem ID, or URL and press submit to fill out an appropriate template that can be pasted into a Wikipedia article"
 * Citation template generator (user:holek)"This is a citation template generator. Using it, you can quickly fill in the citation templates in various language editions of Wikipedia. Please fill in the data (ISBN, PMID, WWW) in the fields below, and the script will try to complete the templates. Parsers for ISBN: ISBNdb.com, LoC, DNB, NUKAT"
 * HTH. --Atlasowa (talk) 18:36, 19 February 2014 (UTC)
 * Thanks. The second is indeed Diberri, and it's not working for ISBNs any longer (at least not for me/in Firefox 26).  It works for PMIDs.  Whatamidoing (WMF) (talk) 19:47, 19 February 2014 (UTC)
 * Atlasowa, if we can't get a firm estimate, I will at least talk to the development team at our next meeting about how they want to organise the testing/deployment for this tool. I should have said above "when we have a testable version .." PEarley (WMF) (talk) 04:01, 20 February 2014 (UTC)
 * Thank you, that sounds good! :-) --Atlasowa (talk) 16:46, 20 February 2014 (UTC)

Thank you for update. I secretly hope that it really will be a matter of weeks.--Vojtech.dostal (talk) 14:16, 24 February 2014 (UTC)

Copy-paste then edit references
In wiki-text, in order to create a new reference I often copy-paste an existing reference and then edit the content - this saves a lot of time instead of using the template generator every time. Is there a way this could be implemented into VE?--3family6 (talk) 15:26, 20 February 2014 (UTC)


 * I know that they're talking about this, so we may get a better solution. However, for right now, here's what worked for me:  Select the old reference and open the reference dialog (click the little book icon).  Select and copy the contents of that ref.  Close the ref dialog.  Go to the new place, and Insert>Reference to make a new one.  Paste the old ref's contents into it.  Then edit it to make a new one (I just changed the date in my example).  Whatamidoing (WMF) (talk) 20:10, 21 February 2014 (UTC)

PMID
The interface is currently jury-rigged to automatically link things like PMID 55555 simply by typing them in. These go directly to one single site, NCBI, which has a decent set of APIs for accessing the major fields of scientific papers. I'd like people to simply be able to type PMID NNNNN and have it be automatically expanded to a full citation, at least in the new VisualEditor edits (though a case can be made for having a bot do it universally). Incidentally, I don't know why there isn't such a bot already. Wnt (talk) 02:19, 21 March 2014 (UTC)


 * If you've already got a ref typed out manually that just happens to include the PMID link, then you wouldn't want to end up with a duplicate. That task might be better suited to a semi-automated script than to a bot.
 * They are supposed to start work on autofilling for the new citation dialog soon. I hope that autofilling PMIDs will be on the list.  (URLs, ISBNs, and DOIs have already been confirmed by James F.)  Whatamidoing (WMF) (talk) 21:59, 25 March 2014 (UTC)

Proposal
1.- As I can see, according to images of Dialog design, is necessary that developers understand how to work citation. You should review this: http://en.wikipedia.org/wiki/Citation. That, because most of styles of citation requires about five fields, but this can change according to the kind or source that is being quoted. Current images show a cheap numbers of fields, and ISBN is not the prioritary field.

2.- You should enable to Wikis' administrators to determine the style of citation and fields provided by the Reference Dialog. This because each Wiki can determine its own standars.

3.- I understand that programming is harder than drawing but, I suggest a reference dialog like the image below.



Reference dialog must allow to recover a source already used and to insert a new source. I suggest dialog with two tabs. The first one could be a new reference dialog with fields to fill and second a tab with the list of sources already quoted. You must be able to select many sources in each reference due is common to use more than one source in a citation. Actually you could add a new reference and use a quoted source in the same step, mantaining the selection of a source quoted in the tab, and adding a new source.

References may be listed in alphabetical order and just as the foodnote format because different sources as books, blogs, films have different fields and is not possible to show it coherently in a list of rows and columns. But you can allow change some information that could change in a citation of the same source. I think in the number of page and date of retrieve. That implies to manage each reference and each source in different way.

If you can edit a reference already used, you could open a dialog that allow you to edit each field given.--SirWalter (talk) 05:43, 26 March 2014 (UTC)

Duplication instead of coordination of efforts?
[//en.wikipedia.org/wiki/Wikipedia:Village_pump_%28technical%29#Adding_citations_in_VE Uh].

Looking at meta:Grants:IEG/Visual_editor-_gadgets_compatibility, this could be really useful for cooperation. How many wikipedia projects do not support citation1 templates, at all? I suspect none or very few (German WP does support all). So supporting citation1 by default might be a good idea. In the WMF Metrics Meeting, April 3, 2014 James seemed to say that all used ref templates needed to be added by each projects admins in JSON...? --Atlasowa (talk) 21:44, 6 April 2014 (UTC)
 * What you're looking at is a community-led project to patch some popular gadgets that are in use at some mid-size and larger projects.
 * James F was talking about what the devs are doing, which will be available to everyone. However, to be usefully available, an admin at each project will have to decide which specific templates to include in the list (if the answer is "none", then the feature silently vanishes), and someone will have to define TemplateData for the chosen templates (if that hasn't been done already).  Whatamidoing (WMF) (talk) 21:42, 7 April 2014 (UTC)
 * What I'm trying to say: I just hope that the VE ref tool, including autofill functionality, will be available to small Wikipedias too, even if they don't have a super talented, active admin with the appropriate programming skills. ;-) --Atlasowa (talk) 14:46, 9 April 2014 (UTC)


 * Definitely. We'll be happy to help communities get started with it, and we'll also have documentation here so that communities can fix things for themselves without needing us directly in most cases. Jdforrester (WMF) (talk) 17:44, 9 April 2014 (UTC)

Feedback on current release
hey folks -- I have not read this page, and am only commenting quickly because I got a notification on my talkpage that you were looking for feedback on the cite tool. So, quickly: I had the chance the other day to teach a new Wikipedian how to edit, in which I didn't try to guide her, but just watched and helped trouble-shoot when she needed it -- so, it was kind of like a mini user-test. Two points I'd make about what happened:

1) She found the editing experience overall using VE extremely user-friendly and easy, including the cite tool. The parts that were challenging for her were all social expectations / editorial policy (like "is it okay to do X" or "how would people normally phrase something like this"), not technical. That's awesome and made me really happy. It was a big change from new editors I've worked with in the past using syntax: typically people found the syntax to be the biggest hurdle, and never got far enough to have any social/editorial questions.

2) The one point where she got stuck was, in the reference dialogue, she didn't know what to put in the field labelled Work, and, she did not see the info roll-over. Because she wasn't sure what to do, she froze and almost bailed from the dialogue. It was not clear to her that the field is optional, although IMO you've followed best practices there: there is no "required" asterisk. So, I'd suggest you might want to think about changing the label from Work to something a little more self-explanatory such as Source Name. Or, maybe you will have a better idea for a fix :)

Thanks & congratulations :) Sue Gardner (talk) 00:25, 29 May 2014 (UTC)


 * Thanks Sue.
 * Good to hear about the new editor feeling welcome. Maybe we should think in longer time about using the opportunity to hint what is and is not appropriate in content terms somehow inside the editor, to answer questions like "is it okay to do X"?
 * The label "Work" is written by the community (in this case, those on the English Wikipedia), so we'll take this suggestion there.
 * Perhaps the description (currently available from the info roll-over) should be more visible – if it was shown all the time alongside the label, do you think this would have helped?
 * Jdforrester (WMF) (talk) 01:48, 29 May 2014 (UTC)

Looks good so far - an overview
The ability to do references in VE is a major step forward. Count me among those editors who abandoned VE, but have turned it back on. However, having said that, I am looking forward to the autofill options (because the current iteration is not yet as functional as my external tools).

One of the more discouraging actions is telling a new editor they need to work on references, and cringing that it will not be easy. I usually direct them to Referencing for beginners. (As an important aside, I see that the page has a section on VE, but it refers to an older version. Is there a more up to date discussion which could be dropped in there?)

The editing experienced will be vastly improved for new editors, as well as experienced editors, when three tasks are completed:
 * 1) Ability to insert a reference using VE
 * 2) Ability to autogenerate a reference from a digital identifier such as ISBN, doi, PMID or from a Google books url
 * 3) Widespread implement of digital identifiers for sources such as newspaper and magazine articles

The good news, from the point of view of the development team, is that step 1 is largely complete, and step 3 is not your job. That's a task I want to take on, hopefully with assistance from others.

Imagine how easy referencing will be if you can identify a source, such as a New York Times article, copy and paste a digital identifier, and a fully formed reference is generated.

I have some specific observations on what I believe is the current iteration VE Reference V4. I'll post my comments in the subsequent section.--Sphilbrick (talk) 13:32, 21 June 2014 (UTC)

Comments on VE Reference V4.pdf

 * General—the page doesn't say, but the implication is that a data base of ISBNs and the associated values exists. I am unclear whether they come from an external source, or wikidata
 * Page 4 I trust developers are aware that a canonical ISBN has four fields, separated by hyphens, so will allow editors to copy in an ISBN which may include no hyphen, a single hyphen after the first field or any hyphens in any location. I'll also guess that some places will accidentally use another character, whether a minus sign, an en-dash and possibly others. It would be nice if all options could be parsed
 * Page 6,7 The ISBN identifies the name of the publisher and the location, so I am not understanding why these fields are presented. They should be auto-filled
 * Page 8 The year of Publication should also be auto-filled
 * Page 8 The page number cannot be auto-filled, but is so important, it should not be optionally presented, it should always be presented, although it should be allowed to leave it blank.
 * General I do not see any discussion of named references. I think I saw somewhere that there will be a numbering convention, but if I want to reuse an existing reference, I do not see how.
 * Page 9 This screen implies there are only two cases: Case 0—the IBSN is in the database and Case 1—the ISBN is invalid. At a minimum, I am fairly certain there can be valid ISBNs not in the database (those issued very recently). I think there are other cases as well, I will try to follow up with a list.--Sphilbrick (talk) 13:36, 21 June 2014 (UTC)

ISBN cases
Following up on a point made in the prior section, I think there are several cases relating to the status of an ISBN. While it may be that multiple cases generate the same response, it may be useful to consider the cases.

I am not yet clear on where the information on ISBN is housed, but wherever it is, I resume there must be some lag. If a publisher with a group of ISBNs decides to publish a book, it seems plausible they might refer to the ISBN, if only in a press release, on some date prior to the information being added to the data base.

That case is different than someone typing in an invalid ISBN. While most people will copy and paste, someone might type (and mistype) or the original source might have made a mistake. The check digit helps identify those errors. At a minimum, I would like to see two different messages:
 * 1) The ISBN you supplied is not in the data base
 * 2) The ISBN you supplied is not a valid ISBN

The reason for the difference is that in case two, the editor ought to double-check the value, as it is certainly wrong. The editor might choose to manually fill out the other fields, but should NOT leave that ISBN in the field. It is wrong However, in case one, while the editor should double-check, it is possible the value is correct, in which case the entry should remain, and the editor should manually fill out the rest of the fields. I want to ensure that the advice given to the editor is different.

Advanced issues
There are a few non-unique ISBNs. My guess is that we do not have any way of knowing about these in advance, but an editor will notice if they enter an ISBN and it auto fills the wrong information. ASt a minimum, the editor should be allowed to override the fields, I trust this already works. As an advanced option, there might be a check box to fire off a notice to the owner of the database, so that some action can be taken. A really advanced option would present the editor with both options and the ability to choose. I think there are more important things to work on so, given the rarity of the situation, would put this low on the list. See this site for some discussion of non-unique ISBNs.--Sphilbrick (talk) 14:02, 21 June 2014 (UTC)