Parameter overload

Jun 7, 2011 at 6:06 PM

Hi guys,

The commands in this module (and its predecessors) suffer badly from parameter overload.  For any of the WPF auto-generated functions, there are simply way too many parameters due to the number of events you can have, and most users will likely not care about most events.  With that in mind, why not generate the functions with one EventHandler parameter that is a dictionary, pairing string event names (e.g. OnMouseDown -- note the removal of the underscore from the current On_MouseDown parameter names that is unnecessary and that makes it harder to get used to the parameter names) with script blocks that will run when the corresponding event is raised.  This change would go a long way into making many things easier, such as:

1. Consuming the command syntax since there is no help for the generated commands.  Take today's release and invoke Get-Help Get-Thumb and you'll see the current mess I'm talking about that should be completely unnecessary.

2. Opening up an opportunity for event discovery through additional commands that allow you to get a filtered event list (either showing a list of all event names, filterable using wildcards, or a list of all events, assigned and unassigned, also filterable using wildcards on names).

The thinking behind this is along the same lines that I believe parameters need categories so that syntax and help information can be easier to consume, but in lieu of those, you can set up categories yourselves by using parameters that are dictionaries like this.  You can also take this further, providing dictionaries that give you logical groupings for other parameters as well.  For example, in Visual Studio when you are modifying a UI element, you can see an alphabetical list of all properties or you can see a categorized list.  Since PowerShell isn't so great with the alphabetical list right now (given the parameter overload issue), go with categorized lists (e.g. an EventHandler parameter as described here, a Font parameter that encompasses Family, Size, Stretch, Style, and Weight, an Alignment parameter that encompasses Horizontal, HorizontalContent, Vertical, and VerticalContent, etc.).  This would make your commands much easier to use, and it would simplify Intellisense as well (somewhat -- I realize there is a tradeoff here for Intellisense without special handling to allow you to see the valid keys in each dictionary).  Don't be afraid to throw an Advanced parameter in there as well for advanced configuration items that hardly anyone ever uses.

With this set of suggestions, I think at a minimum the EventHandler parameter would help out a lot, along with an Advanced parameter to hide away advanced things that 95% of users will never use.  This would get your command syntax down to something digestable.  Add some commands to list events available for an object/command and I think it would be much simpler to use these than it is today.

Thanks for listening!

Kirk out.

Coordinator
Jun 9, 2011 at 3:28 AM

I tend to agree on the problem of parameter overload and command overload, unfortunately, they're both very hard lines to walk.

The list of commands, for instance, dropped significantly from WPK.  It did so by looking more carefully at what types were generated, but it was also full of little times where I found I cut too much.  The syntax style of ShowUI/boots/WPK is a huge gain in terms of discoverability, but the New- commands are still wrappers of WPF commands.

While I've added some parameters to make some tricky things in WPF easier (-i.e. -Top/-Left/-Row/-Column/-RowSpan/-ColumnSpan/-ZIndex), taking them away from the news is tricky.  For one, it makes the capabilities of the control harder to discover (because there's less to tab through).  For another, it's assuming what the user may want to use.  In the years I've been using scripted UI, I've been constantly surprised by new parts of WPF I've discovered.  It would be very hard to get this set "right".

But, overall, I think commands like Select-Date are the answer to your concern.

I think this is true for a few reasons:

- They are scenario focused, rather than developer focused
- There's a small set of default parameters on these controls, but all other parameters are related to what the command does.  The standard parameters are: -Top/-Left/-Row/-Column/-RowSpan/-ColumnSpan/-ZIndex/-Name)

I expect the number of these controls to grow significantly in future releases, and I expect more and more UI to use these controls rather than the core New-.  Limiting the core New- commands probably will not happen, but more and more commands will be focused on specific scenarios and will have fewer parameters.

Hope this helps,

James

 

Jun 13, 2011 at 2:42 PM
Edited Jun 13, 2011 at 2:42 PM
JamesBrundage wrote:

...taking them away from the news is tricky.  For one, it makes the capabilities of the control harder to discover (because there's less to tab through).  For another, it's assuming what the user may want to use...

I would argue that the capabilities of the control are harder to discover because there is way too much to tab through or browse through with Intellisense -- this encourages users to get lost very quickly.  Assume users are starting from 0 and building up knowledge over time rather than showing them everything and hoping they will sort it out.  The former is the right approach for an IT admin, the latter is the right approach for a developer.  Regarding making assumptions, you need to make assumptions.  PowerShell makes all sorts of assumptions in its design, and that is why it works so well for IT admins.  It gives them the right toolset to get started, and they can get into a more powerful toolset later if necessary because it doesn't stop them.  I think your module needs to take the same approach.  I agree tab-discovery or Intellisense is useful, so it would be worth spending some time identifying the events that are more commonly used than others (OnClick, OnTextChanged, etc.) and making those parameters, with the rest going into an advanced bucket (parameter).  This gives newcomers something to get started with, and if you need to support more events with specific parameters over time you can add them based on what you see your users doing.  That allows you to mitigate any risks/worries about trying to get the set right -- the community would be in a position to tell you what they think and you could adjust accordingly.  Without this approach it's just way too much information for the majority of people who you may want to have as consumers of this.

Commands like Select-Date are one part of the solution, but they are not the entire solution to this concern IMHO.  I'd approach this problem with several tiers of user experience:

1. Beginner: Commands that give you the UI so that you can just call them with a few parameters to get a UI for selecting an item from a list, or creating a new user, etc.

2. Intermediate: Commands like Select-Date that allow you to do common things in a UI that you roll on your own in combination with better parameters for the entire command set.

3. Advanced/Expert: Parameters that provide access to every single thing you can do with the WPF libraries.

Today you have 3 (although as expressed, I think you're exposing these wrong), and you've barely dipped your toes into 2 with Select-Date.  I think you'll get much farther with 1 and the rest of 2 in terms of adoption/usage than with what you have today.

Kirk out.

Coordinator
Jun 13, 2011 at 7:28 PM

I agree that the room to grow is in 1 and 2, not in 3.

What I'd love to have more in focus is what should be in those groups.

For #1, I think it would be great to have very high level commands, like maybe a Get-CommandInput or an  Edit-Object or Edit-Hashtable

For #2, I think we're just trying to make any UI tedium you need often enough simple to do.

For #3, I believe that we're close to done, although we can always make more helper parameters on every command.

What are you thinking should be in each group?

James

Coordinator
Jun 14, 2011 at 3:53 AM

I actually like the idea of having a trimmed-down set of parameters available, because certainly there are a too many, and we only use a few most of the time.

However, so far my record for guessing which commands could be safely hidden hasn't been that great, so I'd hate to try to guess which parameters should be available...

Having said that: if we wanted to do it (since we haven't done it pre-launch), I think we would need to do it in such a way that all the parameters still worked, even though they didn't show in tab-completion (basically, we'd have to parse a ValueFromRemainingArgs array).

 

As a side note, speaking as a someone coming from the WPF developer background, I wouldn't want parameters hidden behind extra constructs ... but I especially wouldn't want to have to guess which ones were hidden.

Jun 15, 2011 at 11:24 PM
Edited Jun 15, 2011 at 11:24 PM

To decide what parameters are used the most, I'd start by looking at WPF code behind published management UI to see what events are used in most cases, properties, etc.  Either that or hash out some useful examples and see what's required for the various controls to make those work.  Basically, research to make sure you get it right, starting with the most common controls people will want to use (button, text box, label, combo box, list box/view, check box, radio buttons, date picker).  Also while doing this it would be better to take a minimalist approach so that you can add more parameters based on community demand, since taking parameters away would mean breaking code.

Also, I agree Joel that it could be lousy to hold back someone who does know WPF.  In that case, maybe parameter sets are the answer, with the default parameter set being the one for the average Joe, offering a limited set of parameters and/or organizing them into buckets as proposed above, and the other one could offer all WPF options.

Once you start this sort of thing, maybe the community could help.  It would be easy to wrap your calls in functions that expose the essentials.  You would just need to make sure you learned how people were doing that so that you could push it back in for everyone.

Kirk out.

Coordinator
Jun 16, 2011 at 9:36 PM

Unfortunately, as I'm pretty familiar with the code behind the management UI in many MS products, there's not a very standard set to speak of.  There are a lot of common scenarios, but these end up using an incredibly complex variety of WPF in order for them to work.

I do think parameter sets are probably a good way to go in order to simplify the default experience.  At the least, it would make accidental positional parameter errors more consistent (iif you put in a 2nd position parameter now, it simply ends up trying to apply it to the last parameter added by the code generator in the type hierarchy) .  A parameter set would at least avoid positional parameter troubles.

I think the Community can play a big role in providing more Select-Date and Edit-StringLists.  I'm not sure how much the community gains by having to make more, slightly less raw New- cmdlets.

Hope this helps,

James