I wrote most of this post back in February but have been too busy with other things to ever get back to it. But this bugzilla I received last night made me think that I wasn't the only one that has had trouble grasping the overall logic of the Eclipse User Assistance system, so I decided to spend the time to resurrect it. I hope it gets a little discussion going.
Drawing Users In
I've been thinking a lot about initial user experience lately as I've been getting ready to release more -- for lack of a better description -- consumer-oriented offerings. As much as I'd like to think otherwise, I keep getting corralled back to the view that no matter how well explained and functional P2 provisioning is or becomes a (large majority?) of people will want to click on a button on your website, download the software and run it. They don't care -- and in fact don't want to even know -- about the Swiss Army Knife. They just want the can opener. Maybe later they'll be happy to find out that they can also use it as a screwdriver (but anyway, isn't that what a butter knife is for?), but in the meantime it would be really nice if when they're rooting around in their drawers for it, it is labeled "can opener" in bright letters or better yet has some visual cues that make it look like it might be for opening cans.
And while some people are like me (and probably you) in that they like to open everything up and experiment, other people like to take the direct route -- they'd like to pull the shrink wrap off of their new can opener box and have a nice little full color tri-folded diagram about how to use the can opener. So, while the rest of us are busy chatting on IRC about the most efficient way to saw the top off of a tomato soup can with a nail file, and writing bug reports requesting that the tooth pick be made out of mahogany rather than plastic ("but mahogany has poor wear characteristics") they're sitting down for lunch. In the most brilliant marketing phrase out of the most brilliant marketing company of all time, these people are referred to as "the rest of us", and they really aren't anything like "us". If by us we mean, "us software developers". When I'm in the kitchen, I prefer Can Openers too. And I use a Mac because there is a lot of technical noise and clutter I don't want or need to know about either.
So, how to make a good first impression? How to lead your users into actually using your software? I don't want the results of all of my efforts to be the unused whatsit at the bottom of the drawer of lost gadgets. At the very least, I want users to tell me why my can opener is useless and send it back for a refund. In order to get to that point, I'm going to need them to use it to try to open just one can. And, if they've never seen a can before, along the way I need to let them know that food is stored in it, that they need to go and buy one at the store first ("remember, you'll need to pay for it before leaving..you'll need money for that, which comes from.."), etc.. And that's what I think initial user experience is all about. Not making assumptions about what users do and don't know while accommodating different levels of user interest, experience and curiosity.
OK, enough technical blah blah blah -- to specifics. One of the many nice things about Eclipse is that it already has an enormous amount of infrastructure supporting User Assistance. And, one of the challenging things about Eclipse -- at least for me -- is that employing that infrastructure is going to involve some fiddly bits and dipping into a lot of different areas.
Help!!
You need some! Really. User's like it!
There are many gaps in the overall Agent Modeling Platform, but the products I'm developing are focussed solely on developing Agent-Based Models and there is a lot to that -- users need to be able to figure out how to use the can opener, but they also need to now why and for what they might want to use one. We're lucky enough to have one Manual for an earlier related tool (written by Damon Centola), so I started with integrating that into the docs for Ascape a related tool I worked on for about ten years prior to moving to the Eclipse platform. That meant a lot of work just trying to parse a manual from Word to Apple Pages to HTML output to readable, well-formatted HTML output -- and then moved on to write the Help as well as integrate that with other aspects of the system. Then I started in on creating some (pretty extensive and reasonably complete, I think) user documentation including design overviews, user tools, and examples. By the way, it sounds like an obvious point, but it's good to think a lot about how your documentation is organized. The basic documentation outline for the core Eclipse projects is very good, and while the overall design won't fit perfectly for every project, it's a good place to start and following the common outline provides a seamless experience to users as they move from one Eclipse related tool to another.
The Eclipse TOC editor works quite well for all of this -- there is only one plug-in point to maintain and the maintaining hierarchical structures is easy. Even better, the Eclipse ecosystem now supports some really good tools for creating and most importantly maintaining help content and doing so in a distributed automated way. A number of months back I spent a great deal of time stealing and modifying XText's documentation system. Now we can write all of the AMP documentation in WikiText, launch an ant script, and get all kinds of docs automagically generated. When complete we had nearly two hundred pages of PDF text including the converted Ascape manual, as well as online help and Eclipse integrated help.
Welcome!
The next piece is providing a way for users to be guided into actually using these cheat sheets, references and so on. For that, Eclipse has the welcome screen. The welcome screen is a really nice feature of Eclipse that is under-appreciated and a bit under-utilized. Part of that may be that it is surprisingly difficult to get up to speed with how to use it. There are a number of pieces that have to work together -- a theme I'll return to below -- and you have to poke around quite a bit to figure out where the points of integration are with other projects. For example, for my IDE build, I wanted to be able to turn off some help items that my users probably wouldn't need -- like plug-in development samples -- while keeping some they would, like for (the perennially problematic) SVN integration.
What you end up with is really useful -- if users use it. But I've watched a fair number of neophyte users start out with the software from scratch, and what is the first they do when they launch the software? Click on the "close" button to get rid of the this weird view that is blocking the software! That's in large part due to the initial Eclipse start page that had a bunch of cool symbols on it but really, it's actually not at all apparent why it would be at all useful. So the first change to make for an IDE build is to change the style to Slate, which brings up the four or five main categories along with a description of why they might be useful.
Cheat Sheets
I'd already spent some time getting up to speed on Cheat Sheets. Cheat Sheets aren't something that I personally use a lot -- they are generally a bit to linear feeling for me -- but I'd probably benefit from doing so, just as I'd probably benefit from reading the damn manuals before blindly diving into implementation! My fellow developer and ABM tool user Ed Mackerrow has been pushing me to use them more as he's found that they work really well for easing people into tools.
Now that I'm beginning to work with them a bit more, I'm starting to think of cheat sheets as less clingy versions of Wizards -- they walk you through doing something useful, but when you've done it a few times they don't hang around wanting to hold hands with you all of the time. And they're a lot easier to develop than Wizards.
Generally the cheat sheet authoring process has been really straightforward. If you don't use them and have any kind of product or set of features involving getting people through two or more non-obvious steps, then you really need to try it. (Is there a cheat sheet cheat sheet?)
But as with the Welcome system, the cheat sheet integration process is not so easy. There are some fiddly bits, things that seem more complex that they need to be. Most of that has to do with just mucking around with configuration stuff. In order to create and maintain a cheat sheets for multiple nested groups, one has to define separate cheat sheets for each sub-group, link those together, and then link those to plugin cheat sheet definitions. At each level, you create and maintain names and IDs. So for one group, we need:
- Parent cheat sheet name and id
- Parent cheat sheet file name
- Group name
- Child cheat sheet names
- Plug-in id, name and client link.
If you decide to change the name of one cheat sheet, that can can be one file name, three separate files, and seven text entries to maintain! For me this also creates a lot of cognitive dissonance. Coordinating these kinds of artifacts is a common problem in software design, especially within a large pluggable set of tools, but I think it comes up quite a bit in Eclipse infrastructure. I'll pick up on that general theme below. I'll also talk about how I think the user experience could be improved.
Connecting it all Together
One of the coolest and least appreciated aspects of bundled documentation is the ability to make the documentation interactive. You can call commands or refer to existing cheat sheets.
Calling commands from Help
If I'd known how easy this was, I would have done it much earlier. Something else you really should try, as it provides a nice solution that sits between cheat sheets and screenshot oriented tutorials in the suer experience. In my case, I thought it would be neat if user's could actually run example models while reading about them in the Documentation! So, here's how to call code directly from help.First you implement a live help action:
public class ExecuteJavaModelAction implements ILiveHelpAction {
String javaPath;
/**
* Launch the Escap model.
*
* @see java.lang.Runnable#run()
*/
public void run() {
IPath path = new Path(javaPath);
EclipseEscapeRunner eclipseRunner = new EclipseEscapeRunner();
IProject javaProject = ResourcesPlugin.getWorkspace().getRoot().getProject(path.segment(0));
IPath fullPath = path.removeFirstSegments(1);
try {
javaProject.open(null);
eclipseRunner.open(javaProject, fullPath.toPortableString(), fullPath.lastSegment());
} catch (CoreException e) {
throw new RuntimeException(e);
}
}
/**
* Define the Java pah to the model node.
*
* @param data
* @see org.eclipse.help.ILiveHelpAction#setInitializationString(java.lang.String)
*/
public void setInitializationString(String data) {
javaPath = data;
}
Here, since I need to refer to a model within a project within the workspace, I need to discover where that workspace and project are. Otherwise the code is very straightforward.Then, we just need to define an embedded javascript to actually execute it:
<a href='javascript:liveAction("org.eclipse.amp.escape.ide", "org.eclipse.amp.escape.help.ExecuteJavaModelAction",
"org.ascape.escape.models.brook/edu.brook.sugarscape.GAS_II_1")'>This is covered nicely in the Eclipse help (as one would hope it would be!) though why not have a working example here!
Calling Cheatsheets from Help
It's pretty easy to get to Help from Cheat Sheets, but what about getting from Help to Cheatsheets? It's actually pretty easy though for some reason it was at first opaque to me and isn't actually spelled out in Help anywhere. Instead it's one of those things where you have to put two and two together but it can be difficult to locate where those two twos are to begin with. So here is how it is done:
Please follow this <a href='javascript:liveAction("org.eclipse.ui.cheatsheets", "org.eclipse.ui.cheatsheets.OpenCheatSheetFromHelpAction",
"org.eclipse.amp.escape.loadProjects")'>cheatsheet</a>.But cheat sheets still have some significant usability issues I think -- and like the other issues, they aren't really technical, but have to do with the overall design approach.
Hey, I still can't open this can!
Which brings us back to my reason for resurrecting this post. It's that whole can opener thing. The Eclipse user assistance capabilities, especially when compared to what's available on many platforms is quite complete. Overall, the Eclipse toolset and User Experience provides a powerful, world class set of user tools. There have been enormous efforts in improving the User Experience, most especially I think with provisioning -- but I still think we can do better. For example, it's hard to explain exactly why, but somehow the Eclipse User Assistance experience still seems a bit disjointed.
Part of making the most of the tools is for all of us to (yeah, obvious, right) use them, and that means I think improving the tools for authoring and integrating help so that small teams can get up to speed on them quickly to produce good help. But part of it is being willing to rethink aspects of the user experience. And thinking clearly and in an unbiased way about how all of the different pieces fit together.
How do we do that? I don't know exactly, but I've observed that one of the biggest challenges to the improvement of Eclipse is this attitude: "We've always done it that way, and it makes sense to me.." Well, of course it makes sense to you, you've been using the tool for five years! Then it's, "Ok but, no one has ever complained about it, they should file a bugzilla". The last feedback you're going to get is from new users -- they don't know how to use the software, so how likely is it that they're going to know the culture of bug reporting? And so here's the problem with that response: new users don't complain, they just go somewhere else. Or, if they stick around, they quickly learn that that is just the way things are done and its not likely to change, because everyone is used to it. And more than anything else -- which constantly surprises me, knowing how imperfect most software really is -- they figure that they're just missing something that must be obvious to everyone else!
Which is why I love the Bug that I mentioned at the beginning of the post. Here's a user that didn't get it, and let us know that he didn't get it. Now, I know Scott and he's not a dumb guy. He's actually a really smart guy -- a Computer Science Ph.D. and just finished a postdoc at Caltech. And he's done a lot of development for ABM tools based on Objective C on OS X. So what's he missing? The issue he is having here is being directed to a cheat sheet from the welcome screen.
The Eclipse developer (me) and platform (us) point of view: I've put together a great Welcome setup, and even included some sample models. All the user has to do is click on the Samples button, click on the Example Models button and he get's directed through the simple process of downloading and installing some example models from the version control system. Neat, huh?
Scott's point of view: I clicked on a button and the window went away and nothing happened.
Now Scott didn't know that he was being asked to use a cheat sheet. The Welcome screen just tells him that he's going to be able to load some example models. Well, if you've done this before, you know that you're gong to get a cheat sheet and you just need to follow the steps that are layed out for you. Once you know what a cheat sheet is, it's pretty clear what it's for. But what if you've never used one before? Cheat sheets actually open into a small window on the right side of your screen. They're surprisingly easy to miss. Not for you and me, but for a new user. Worse then all of this, loading some of the models (the one's I can't host on Eclipse for licensing reasons) requires SVN, and (as all long-time Eclipse users are only too painfully aware) if you haven't installed Subversion yourself, it won't work, and you won't know why. So even if the Cheat Sheet were obvious it still wouldn't work out of the box. Which means that I need to add something to the cheat sheet that says "First you need to install Subversion..". Argh! I think it will actually be easier to just move the example models.
Perhaps you have other User Experience examples to share. It's always a bit difficult to share examples because you end up critiquing a small aspect of work that someone has put a great deal of effort and thought into. But doing so is critical to having a culture of continual improvement. In that spirit, here are a couple of examples I've gleaned from users..
What's the difference between Help Contents and Dynamic Help? And where does "Search" fit into that? Another one is the Eclipse downloads -- there have been improvements to the download page itself, but I still get questions all the time from users asking me what version of Eclipse they should download. Hey, that's easy, right? OK, for the Eclipse developers out there, we can find anything we need quickly and easily, but please imagine for a minute that you are a new user facing this matrix of choices. Now, there are all kinds of good rationales for not changing things -- (yep) that's the way we've always done it, and conversely the users need to learn to use what we're trying to give them, and -- but I'll go out on a limb and say that user experience trumps pretty much every one of these.
Perhaps you've got some ideas you'd like to share. Or perhaps I'm making a mountain out of a speed bump on the entrance ramp to the exciting world of Eclipse, but I'll just suggest that before you think "that's obvious" put your self in the mind of a new user. And then ask yourself "is that really obvious, or am I just used to it?"
