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:
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
Nobody will read the yellow box at the top.
The capitalisation of the top bar is inconsistent with the rest of the UI.
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
It's easy for a user to get the Data and Pattern panels mixed up.
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.
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.
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.
Confusing, inconsistent labels.
"Results" -> "Output"
"To GUI" -> "In a new window"
"To pipeline" -> "To shell pipeline"
I could probably give you a lot more useful advice if I understood exactly what the options did!
I can't understand the option labels.
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.
"delim." looks messy and unprofessional, especially when you use the full word elsewhere.
Repetition of "delimeter" hints at refactoring.
Refactor your layout.
# SUGGESTED COMMAND LINE
I like how the colour and font suggest the purpose of the command line text.
The title doesn't fully reflect that this command line has been generate for you to use. "Suggested" doesn't have the right connotation.
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
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.
I'm not 100% sure what the Save button does.
Maybe you meant "Save As.."?
What does the Execute button do?
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?
NimbleText 2.0: More Than Twice The Price!
A Computer Simulation of Creative Work, or 'How To Get Nothing Done'
NimbleText 1.9 -- BoomTown!
**This** is how you pivot
Art of the command-line helper
Go and read a book.
Slurp up mega-traffic by writing scalable, timeless search-bait
Do *NOT* try this Hacking Script at home
The 'Should I automate it?' Calculator
aaron swartz: the early works
Finding (and removing) duplicate files on your hard drive
Harvey, a .net chat server built with RabbitMQ
So your domain has been stolen. What now?
kv can remember it for you, wholesale
Hello IT Department
Dialog Between a Man and His Vista Laptop
NimbleText 1.6, Codename Jetboat
On Task Hoarding and Todo Bankruptcy
Developer UI Done Right: Mercurial Commandline!
Rediscovering the Amstrad CPC 6128
The Correct Order for a First Time Viewing of The Lord Of The Rings
A new era for Android.
Mind-boggling Demo of New Gaming Genre, aka Folder-Based Hangman, aka Fun with Recursion
Complete secretGeek Archives
TimeSnapper: automatic screenshot journal
25 steps for building a Micro-ISV
3 Minute Guide Series
Universal Troubleshooting Checklist
Top 10 SecretGeek articles
Now at CodePlex
RealTime Online CSS Editor
How to be depressed
You are not inadequate.
the little schemer
The Best Software Writing I
The Business Of Software (Eric Sink)
dot net kicks
Human Link Machines
a continuous learner's weblog
weekly link post
LogEnvy - event logs made sexy
Computer, Unlocked. A rapid computer customization resource
BrisParks :: best parks for kids in brisbane
PhysioTec, Brisbane Specialist Physiotherapy & Pilates