Change 620665 had a related patch set uploaded (by Awight; owner: Awight):
[mediawiki/extensions/VisualEditor@master] [WIP] Move parameter description out of popup

https://gerrit.wikimedia.org/r/620665

Just to show VE's current approach to an overly long template description text,
Autocomplete:

The "more / less" paradigm isn't applied, yet.

Example template invocation: https://en-wmde-templates-alpha.wmcloud.org/wiki/User:Adamw?veaction=edit

Live on the test instance:

Note that the collapse functionality is provided by an off-the-shelf jQuery plugin, and I haven't fine-tuned it to exactly match the mockup. Please advise whether the small discrepancy is worth correcting.

Wow looks great!

Good question - ideally the entire description would take two lines so that more parameters could be seen at a time. Despite this, I don't think it is necessary for the "... More" to be at the end of the second line for this first pass. There are a few other things that I would prioritize fixing:

• Align all text. Currently the description is starting a few px to the left of the label.
• Now that the full description has been moved below the label, there is no reason for the double listing of 'Field is required' (shown with asterisk) or the example / default (shown in the input field.) Can we remove these from the description? It's also causing an odd thing where it isn't included in the two line count. I noticed that when these are added and it exceeds two lines, the 'More' button isn't shown (see image below).
• Other times, the description really is two lines, yet the button is still shown. I couldn't find a pattern here but included an example below.

Double example and required text:

Two line issue:

Ready for another round of review, changes have been pushed to the test instance. The position of "More" is hard to control, sometimes it will appear at the end of the second line and sometimes on a third line--let me know if it's good enough for now!

Much improved! Thanks for the updates. It's still a little funky in small ways but I think it's definitely workable for the usability test.

In T260147#6392399, @ECohen_WMDE wrote:

Much improved! Thanks for the updates. It's still a little funky in small ways but I think it's definitely workable for the usability test.

Feel free to suggest more tweaks! It's easy to fix everything I did here, with the exception of the More/Less collapse (this would be "medium").

Ok, will share but if anything seems to cause more trouble than it's worth then it's fine to drop them.

• I would make the spacing tighter - my fault for not including any specs in the initial mocks I uploaded. I think the line-heights should be big enough that 4px margin between the label/ description and 4px between description/input field should work well.
  

• The two line issue I described above is much better since now 'More' is on the second line, but it's still there. Seems like the cut-off for truncation is a bit too short and descriptions which fit on two lines are being cut in the middle of the second line. For example, in the 'Infobox officeholder' template it's happening on both parameters: alongside and order.

In T260147#6392761, @ECohen_WMDE wrote:

• I would make the spacing tighter - my fault for not including any specs in the initial mocks I uploaded. I think the line-heights should be big enough that 4px margin between the label/ description and 4px between description/input field should work well.
  

Done, this is on the test instance now.

• The two line issue I described above is much better since now 'More' is on the second line, but it's still there. Seems like the cut-off for truncation is a bit too short and descriptions which fit on two lines are being cut in the middle of the second line. For example, in the 'Infobox officeholder' template it's happening on both parameters: alongside and order.

I played with this and couldn't improve the situation, yet. The plugin was supposed to do line-based truncation but something about VisualEditor initializing the elements off-screen is defeating this logic. So I'm crudely truncating at 15 words, it seems to give us roughly 2 lines most of the time. I won't pursue this any further unless it'll be a problem for our experiments.

I think it will work great - don't think there is a need to take it further. And I think the smaller margins made a big difference - thanks!

Ah I have one more small thing (which I think isn't too big). Can the description have the same width as the input fields?

• Can the description have the same width as the input fields?

Thank you for your patience! :-)

Known issues/questions:

• The font size feels like it's to small on my screen (12.6px calculated).
• Can we please not animate clicks on "more"/"less"? Or at least make the animation very fast. The default jQuery animation timing is not only super annoying, it causes performance issues on slower machines.
• The text is probably truncated based on characters or words, not on based on lines. This creates situations where a click on "more" reveals just a few more words, but they all fit in the existing line. The feature is pointless then. (Don't get me wrong. The current implementation is absolutely fine as a proof of concept.)
• Now there is: parameter name, description, the actual input field, and possibly a warning text. When there are many fields that all have all or most of this information, the dialog becomes rather cluttered. It's hard to see where one parameter ends and where the next starts. This was much easier before.
• Clicking the description should focus the input field. Same as clicking the parameter name.
• It might be better to put the new DOM element into the existing ve-ui-mwParameterPage-info element. At the moment they follow each other, which requires to repeat certain styles.
• The ⓘ popup shows a lot of stuff: description (now obsolete), required or deprecated (both shown as icons), default and example. This is indeed all redundant, with one exception: When there is a default and an example, only the default will be shown as a placeholder.
• This actually raises a question: What's the point of having default and example, when they behave exactly the same?
• …

Can we please not animate clicks on "more"/"less"?

We should consider the ideal animation here and make it the same for clicking on both more and less (currently it's only on more). Possibly ideal is none (esp for the performance issues), but I'll flag this to take a look at before final implementation.

The text is probably truncated based on characters or words, not on based on lines.

Yes, @awight and I were going back and forth on this. The current behavior is good enough for now but agreed, not ideal. For the eventual implementation we would have to fix this and make sure "... More" is only at the end of the two lines and only shows if needed

It's hard to see where one parameter ends and where the next starts.

I see what you mean, but I think this is something that can be fixed with spacing. It is more information, but I think it is all useful/helpful information to have visible. I'll mark this as something to explore. It will also be interesting to see if this comes up in usability testing (planning to test both current and new).

Clicking the description should focus the input field. Same as clicking the parameter name.

Agree. Thanks for catching this.

This actually raises a question: What's the point of having default and example, when they behave exactly the same?

Clearly the community agrees on this because when analyzing the TemplateData we found that there are very few templates which have both. Do you know of any difference in their behavior (other than the prefix when shown in VE)? Particularly since autovalue actually behaves as the default and there is currently no place that the autovalue is displayed to users. Maybe we should check if people are listing the same value for default and autovalue. Unless we actually change TemplateData to merge default and example (or default and autovalue) though, we should consider how they are shown when more than one has a value.

Clicking the description should focus the input field. Same as
clicking the parameter name.

The user should still be able to select text in the description, for example to look up something mentioned there.

This actually raises a question: What's the point of having default
and example, when they behave exactly the same?

Maybe the behavior shouldn't be the same? I imagine these make sense in different situations, a default could be used as the field's placeholder value, but examples would contain specific values that won't be used verbatim, they are to demonstrate a general pattern. The different usage would explain why so little overlap. I don't see the argument for merging.

My freshly-formed, 1 cent opinion is that the example value shouldn't appear as field placeholder text, precisely because this confounds it with a default value. If the field is left empty, the parameter does not have the example value yet it still appears. Also, I would expect to be able to set an array of example values for a field, to show the range of potential uses and inputs.

Clicking the description should focus the input field. Same as clicking the parameter name.

The user should still be able to select text in the description, for example to look up something mentioned there.

Also agree. Perhaps it should be re-written as, clicking '... More' to expand the description should also focus the related input field. The text should remain selectable and not act as a button/link itself.

Re: examples and defaults. Yes, I don't think they should be merged if they have different purposes. But if they have different purposes, they should have different behavior - and from what I understand the only difference is the prefix added to the value (e.g. or Default:) and that the default is given higher priority (meaning if a parameter has both, the default is shown as the placeholder). I think it's worth discussing what the ideal behavior and placement is, including autovalue as well. I feel like I still need to learn a bit more about their uses/behavior.

In T260147#6405424, @ECohen_WMDE wrote:

Also agree. Perhaps it should be re-written as, clicking '... More' to expand the description should also focus the related input field. The text should remain selectable and not act as a button/link itself.

That sounds right to me!

But if they have different purposes, they should have different behavior

For sure, and we should tease apart cause and effect. I can imagine that the nearly identical behavior has led towards a less discriminate use of the two attributes. Because of this, I feel justified in talking more about the theoretical meaning of "default" vs. "example", which we can apply back to the degenerate feature existing today.

the default is given higher priority (meaning if a parameter has both, the default is shown as the placeholder)

+1 seems like a good decision, so far.

I'm not enthusiastic about "the example" (more than one should be allowed) ever showing up as a placeholder in the first instance. What do you think? Maybe we can get rid of "example" entirely, using the argument that each example ideally should include its own documentation, so this might as well be done as markup built into the description block?

"autovalue" is intriguing too, functionally it's similar to the "default" placeholder, but drawn in solid black and editable rather than gray? This might already be a good implementation, though of course more discussion would be healthy and probably teach us something.

Sorry, my comment was misleading. I think the current state is fine for the prototype phase. What I listed are questions I would like to re-validate after we collected more input from user tests and such.

the community agrees on this […] there are very few templates which have both.

This confuses me a bit. How is this an agreement?

[…] any difference in their behavior (other than the prefix when shown in VE)?

There is indeed a tiny difference: When you expand the left panel, you find the list of parameters repeated. In this list, a parameter turns gray if it's empty. Having a default value disables this.

merge default and example […]

Note I was never arguing for a merge, merely asking a question. Personally I think the behavior should be separated further to better reflect the intention.

autovalue actually behaves as the default […]

There is a difference. As autovalue is documented it will be automatically inserted into the article when the user doesn't enter anything else. The default doesn't do this. The best example for an autovalue are maintenance templates with a parameter that documents when the template was added – i.e. the current date. While it's possible to think of this as some kind of "default", it's one that changes every day. The idea is to have a tiny snippet of dynamic wikitext in the autovalue that "magically" replaces itself with the current date the moment the article is saved.

However:

• It doesn't work. (T4700 is mentioned as a reason.)
• It's currently entirely unused in VE.

This confuses me a bit. How is this an agreement?

Good point. I think that was bad wording on my part; it's an assumption I'm making. If they had significantly different uses or behavior then I think it would be more common for a parameter to have values for both. It could also just be that when a parameter has a default, it often also functions as the example. I agree that further differentiation, not merging might help.

I discussed with @Lena_WMDE and we decided that the ideal behavior is for the example to be added onto the description. Then it shows above the input field if there is no description or a short one. Otherwise, it's also shown on clicking '... More.' This I think will be particularly useful for long examples, such as Adam's explanation when maybe more than one example should be listed. It would also be visible if there is a default. Plus, it remains visible as the user types their input and can be used as a reference for formatting.

Lastly, I think it's odd that autovalue is not used/displayed in VE. I think I'm still not 100% clear on the difference between autovalue and default though. Is the default also automatically passed in when the parameter is added but left blank? Is the difference just that the default is static while autovalue is dynamic? I've seen templates used for default though, like PAGENAME.

In T260147#6409343, @ECohen_WMDE wrote:

Is the difference just that the default is static while autovalue is dynamic?

Weirdly enough, it's sort of the opposite. When saving a template invocation with a parameter left blank, a default will be applied at the time the template is rendered. If the default changes, any template where the parameter is blank will exhibit the new value. An autovalue will be permanently substituted into the invocation the first time the template is saved, and from then on the parameter's value is static.

That probably isn't helpful...

Very helpful! Thanks @awight !

I think then what makes the most sense is that the default stays as the placeholder in the input. Then the autovalue automatically placed into the input, but as editable text.

Do you think it makes sense to make a new, separate ticket for the placement of example/default/autovalue then? I think the bulk of this ticket is done (moving the description) and this is just a side conversation that arose in the process.

In T260147#6409516, @ECohen_WMDE wrote:

I think then what makes the most sense is that the default stays as the placeholder in the input. Then the autovalue automatically placed into the input, but as editable text.

That sounds good to me, as well as your comment (elsewhere?) about putting "the example" into the description again.

Do you think it makes sense to make a new, separate ticket for the placement of example/default/autovalue then? I think the bulk of this ticket is done (moving the description) and this is just a side conversation that arose in the process.

+1 it also makes sense because we'll probably want to track this question separately when discussing with WMF later.

To be honest I would not touch autovalue at all – other than documenting it as unused. Well, except there is demand to finally implement it, which I haven't seen.

Change 624676 had a related patch set uploaded (by Awight; owner: Awight):
[mediawiki/extensions/VisualEditor@wmde-templates] [POC] Move parameter description out of popup

https://gerrit.wikimedia.org/r/624676

Change 624676 merged by Awight:
[mediawiki/extensions/VisualEditor@wmde-templates] [POC] Move parameter description out of popup

https://gerrit.wikimedia.org/r/624676

Change 620665 abandoned by Awight:
[mediawiki/extensions/VisualEditor@master] [POC] Move parameter description out of popup

Reason:
Moved to a gitlab branch, https://gitlab.com/wmde/mediawiki-extensions-VisualEditor/-/tree/param-description

https://gerrit.wikimedia.org/r/620665

@awight Is it a quick change to switch the number of characters it truncates at? Ideally 80 characters or ~ 1 line.

Also, you said that the way this is working is finicky - so feel free to say it's not worth the effort at the moment. But, I was wondering if it's possible to give it a cutoff, so that if the amount that is hidden is 10 characters or less, it just shows it?