Art of the command-line helper

The scariest code I ever wrote is the dialog in NimbleText that helps you use the command-line.

Much smack has been written in the past about confusing command-line helpers in other apps, so I set out to build this dialog with great trepidation in my heart.

Joseph Cooney has laid into two particular apps, a gui for wget, and a gui for robocopy. Even Jeff Atwood had a stab at wGetGui.

Here's what they looked like:

And here's a typical user response upon first encountering such a command-line helper:

I downloaded both these apps and tried them out.

Okay, the kindest thing you can say is that they are comprehensive, and with their use of tooltip text they do offer a little more help than the screenshots would suggest.

But they still give an immediate slap in the face to the end user. Something I want to steer away from.

So command-line helpers are a challenge. And to increase the pressure a little more: the command-line feature in NimbleText is only unlocked if you buy a license. If I'm expecting this feature to be worth money, they I really have to not screw it up.

What I did.

The first thing was to use descriptive labels, instead of verbatim option names. Instead of having a checkbox named "--rawdata" I'd have a label that said "Raw data". While this is only marginally more readable, it hopefully decreases the effect shown above.

Next I added a textbox at the foot of the form, where the command-line you've created is written, live, so you can see the output of your furious clicking.

There's a button for save, so you can save your command-line straight to a batch file. (It works from powershell too). A copy button, to put the command-line into your clipboard, and an execute button, which launches a cmd.exe process, and tries out the command-line immediately.

Other than that, I just sweated the small stuff. Alignment, spacing, capitalization, tab order, tool tips, everything as consistent as possible.

What I probably failed to do was give The Dialog any breathing space.

(And looking at the screenshot now I see a slight inconsistency with spacing, which should be fixed by the time you look at the application itself.)

Here's what I came up with:

Any suggested improvements? Please send them in.

'Jimmy' on Thu, 07 Mar 2013 11:39:29 GMT, sez:

Hi

All great but i'm not convinced. Why not invest time in decent help and switch to a platform with good intellisense? I'm talking about PowerShell here.

'Simon' on Thu, 07 Mar 2013 14:48:33 GMT, sez:

I'd make it a bit more sentencey in places, e.g.

|-Send the result ----------------------|
|
| o To this file: |__________|

and so on.

'Doeke' on Thu, 07 Mar 2013 14:50:54 GMT, sez:

Joseph Cooney said something about dialogues should be landscape, not portrait. I'm not sure, however.

'lb' on Sat, 09 Mar 2013 10:19:14 GMT, sez:

@Simon: Done. Will be in next release.

@Doeke: Yes, I'm happy with the portrait orientation.

I received an excellent email with a few pages of excellent suggestions, bug reports and thoughts from Yaron Davidson. That will also help with the next release.

'Pitarou' on Tue, 12 Mar 2013 21:09:47 GMT, sez:

Critiquing dialogues like this is part of my MA course, so apologies if this degenerates into academic nitpicking. :-)

DON'T make it more sentencey. Simon wants it to be more sentencey because he admires your handiwork and enjoys yoru splendid prose. Simon is not your target user. Think, instead, about the MINIMAL COGNITIVE EFFORT needed to GET STUFF DONE.

# TOP BAR and YELLOW BOX

## Problems

Nobody will read the yellow box at the top.

The capitalisation of the top bar is inconsistent with the rest of the UI.

## Solutions

Replace the yellow box title that repeats the text in the top bar. Put a "What's this?" button at the top right.

Pick a capitalisation style and stick to it.

# INPUT DATA and INPUT PATTERN

## Problem

It's easy for a user to get the Data and Pattern panels mixed up.

## Solution

Make the Data textbox at least twice as large as the Pattern textbox. This makes the difference clear because we expect the data to be longer than the pattern.

## Problems

Repetition of "Input" hints at refactoring opportunity.

"raw text" is ambiguous.

The association between the radio buttons and the other UI elements is not visually apparent.

The textboxes are active even when the "From file" option is selected.

## Solutions

Relabel the panels "Data" and "Pattern" from, and nest them in a panel labelled "Input". Relabel "From Raw Data" to something like "From this textbox".

Move the "From file" button closer to the File selection box.

Move the "From this textbox" buttons right and down a little, so it's closer to and vertically centred with respect to the textbox.

Grey out the input boxes when the associated radio button isn't selected. Experienced users might not like it, but it will make matters clearer for novices, and the novices are the ones you need to impress most.

# RESULTS

## PROBLEM

Confusing, inconsistent labels.

## SOLUTION

"Results" -> "Output"
"To GUI" -> "In a new window"
"To pipeline" -> "To shell pipeline"

# OPTIONS

## Notes

I could probably give you a lot more useful advice if I understood exactly what the options did!

## Problem

I can't understand the option labels.

## Solution

Research the language your target audience uses. Maybe you could browse Stack Overflow to figure out the language your target audience uses?

Tooltips and a help button for more detailed information.

## Problem

"delim." looks messy and unprofessional, especially when you use the full word elsewhere.

Repetition of "delimeter" hints at refactoring.

## Solution

Refactor your layout.

# SUGGESTED COMMAND LINE

## Praise

I like how the colour and font suggest the purpose of the command line text.

## Problem

The title doesn't fully reflect that this command line has been generate for you to use. "Suggested" doesn't have the right connotation.

## Solution

The best I can come up with is "Here's your command line..."

But it's a bit out of keeping with the rest of the UI. Can anyone think of something better?

# BOTTOM BUTTON BAR

## Notes

I could give more advice if I knew exactly what the buttons did, but here are some general suggestions:

1. Put the buttons that use the generated command line closer to the command line.

2. Put buttons like "Close" that require some commitment from the user separate from the other buttons.

## Problem

I'm not 100% sure what the Save button does.

## Solution

Maybe you meant "Save As.."?

## Problem

What does the Execute button do?

## Solution

Find a way to make it clear!

# THOUGHTS ABOUT RESIZING

Do you want to give the user the option of resizing the text boxes?

What happens if, say, you have very filenames in the commandline, so it's larger than can fit into the box?

What happens when you resize the window?

'Doeke' on Sat, 16 Mar 2013 12:21:47 GMT, sez:

Because you have an Execute button, the user also needs to know the current path. And do you also provide hints, when a file doesn't exist?

name


website (optional)


enter the word:
 

comment (HTML not allowed)

All viewpoints welcome. Incivility is not tolerated, such comments are deleted.

 

TimeSnapper_{Know thyself!}

I'm the co-author of TimeSnapper, a life analysis system that stores and plays-back your computer use. It makes timesheet recording a breeze, helps you recover lost work and shows you how to sharpen your act.

 

NimbleText is a Powerful FREE Tool

I wrote this, and use it every day for:

• extracting data from text
• manipulating text
• generating code

It makes you look awesome. You should use NimbleText, you handsome devil!