DevAssistant Heuristic Review Part 1: Use Case Walkthroughs

You might be asking yourself, “What the heck is a heuristic review?”
It’s just a fancy term; I learned it from reading Jakob Nielsen‘s writings. It’s a simple process of walking through a user interface (or product, or whatever,) and comparing how it works to a set of general principles of good design, AKA ‘heuristics.’
To be honest, the way I do these generally is to walk through the interface and document the experience, giving particular attention to things that jump out to me as ‘not quite right’ (comparing them to the heuristics in my head. 🙂 ) This is maybe more accurately termed an ‘expert evaluation,’ then, but I find that term kind of pompous (I don’t think UX folks are any better than the folks whose software they test,) so ‘heuristic review’ it shall be!
Anyway, Sheldon from the DevAssistant team was interested in what UX issues might pop out to me as I kicked the tires on it. So here’s what we’re going to do:

• Here in Part 1, I’ll first map out all the various pieces of the UI so we can get a feel for everything that is available. Then, I’ll walk through four use cases for working with the tool, detailing all the issues I run into and various thoughts around the experience.
• In Part 2, I’ll analyze the walkthrough results and create a categorized master list of all the issues I encountered.
• In Part 3, I’ll suggest some fixes / redesigns to address the issues catalogued in Part 3.

Okay – ready for this? 🙂 Let’s go!

Setup Wizard Mapping

(This is the initial dialog that appears when you start DevAssistant.)

I’m starting this review of DevAssistant’s GUI by walking through each tab and mapping out a hierarchy of how it is arranged at a high level. This helps me get an overall feel for how the application is laid out.

• Create Project
  • C
  • C++
  • Java
    • Simple Apache Maven Project
    • Simple Java ServerFaces Projects
  • Node.js
    • Express.JS Web Framework
    • Node.JS application
  • Perl
    • Basic class
    • Dancer
  • PHP
    • Apache, MySQL, and PHP Helper
  • Python
    • Django
    • Flask
    • Lib
    • Python GTK+ 3
  • Ruby
    • Ruby on Rails
• Modify Project
  • C/C++ projects
    • Adding header
    • Adding library
  • Docker
    • develop
  • Eclipse Import
  • Github
    • Create github repository
  • Vim Setup
• Prepare Environment
  • Custom Project
  • DevAssistant
• Custom Task
  • Make Coffee

Use Case Testing

I’m going to come up with some use cases based on what I know about DevAssistant and try to complete them using the UI.

Use Cases for Testing

1. Create a new website using Django.
2. Create a new C project, using Eclipse as a code editor.
3. Import a project I already have on my system that I have cloned from Github, and import it into Eclipse.
4. Begin working on an upstream project by locally cloning that project and creating a development environment around it.

Use Case 1: Create a new website using Django

I’m not much of a Django expert, so this may end up being hilarious. So I know Django is Python-based, and this is a new project, so I click on the “Create Project” tab, then I click on “Python.” I select “Django” from the little grey menu that pops up. The little grey menu looks a little bit weird and isn’t the type of widget I was expecting, but it works I guess, and I succesfully click on “Django.” Note: the items in the submenu under Python are organized alphabetically.

A new screen pops up, and the old one disappears. I had the old screen (the main DevAssistant window) placed in the lower right of my screen. The new screen that appears (Project: Create Project-> Python -> Django) jumps up and to the right – it’s centered perfectly on my left monitor. It looks like I’m meant to feel that this is a second page to the same window (for example, the way the subitems of GNOME control center work.) Instead, thought, it feels like a separate window because it’s a little bit larger than the first window and it jumped across the screen so dramatically.

This new window is a bit overwhleming for me. First it asks for a project name. I like ponies, and Django does too, so I call my project “Ponies.”
Next, it wants to know where to create the project. It suggests /home/duffy, but man is my home pretty messy. I click on “Browse” to pick somewhere else, thinking I might create a “Projects” subdirectory under /home/duffy to keep things nice and clean. There isn’t a way to create a directory in this file chooser, so I drop down to a terminal and create the folder I want, then fill out the field to say, “/home/duffy/Projects” and move on.
Now, it’s time to look through available options. Hm. This is definitely the most overwhelming part of the screen. Looking through the options… two seem to be related to coding environments – there’s a checkbox for eclipse, and there’s a checkbox for vim. There’s an option to use Python3 instead of Python 2. There’s an option to add dockerfile and create a docker image. There’s a virtualenv option, and a deps-only option. I think I understand all of these options except for “Deps-only,” which is labeled, “Only install dependencies.” If I don’t only install dependencies, then what happens? What is the alternative to clicking that box? I’m not sure.
Anyway, back to the editors. I like vim, but this is a fresh desktop spin installation and I know that doesn’t come with vim preinstalled. I wonder what will happen if I pick vim. I decide to do it.
Oh, and there’s a Github option. It will create a GitHub repo and push the sources there. That is pretty slick; I click that checkbox too and provide my github username. Then I click “Run” in the lower right corner. (Note that a lot of new GNOME 3 apps have the button to progress forward in the upper right.)
Next, pops up a screen that has a log that spits out some log style spew, looking like it’s installing some RPMs. Quickly, a modal dialog pops up that says:

Installing 20 RPM packages by Yum. Is this ok?
[ No ] [ Yes ] [ Show packages ]

The modal dialog has the same problem of being centered to the whole desktop rather than centered along where the parent window was. I like that it offers to show me which packages it’s going to install. I click on “Show packages.” I get a very nice scrollable display in the same window, neat and clean. I click “hide packages” to hide the list. Then I click “Yes” to move forward.
Now things got a bit weird. My whole screen went black. A gnome-shell style black dialog is in the center of this black screen and it is asking for my root password. I don’t think the screen behind the dialog should be black. It feels a little weird. (turns out this was a F21 TC4 issue only.) I type in my root password and click to continue.
And it seems the process failed. (To be fair, I am doing this on an alpha test candidate – F21 TC4 – so the issue may be with the repos and not DevAssistant’s fault.) It says:

Resolving RPM dependencies ...
Failed to install dependencies, exiting.

I like the option to copy the error message to the clipboard, and to view and copy to clipboard the debug logs. It errored out because of a packaging issue, it looks like:

Package python-django-bash-completion-1.6.6-1.fc21.noarch.rpm is not signed
1
Failed to install dependencies, exiting.
Failed to install dependencies, exiting.

There is also a “Back” button and a “Main window” button; I’m not sure which to click. I try “Back” first. That brings me back to the screen I filled all the details in for my project; however I know it won’t work now when I click run.
So at this point, I emailed Sheldon to let him know that I ran into some breakage, and he told me that it wasn’t necessary to test on F21 TC4 – what’s in F20 at this point is reasonably recent and worth doing a heuristic review on. So let’s continue from this point, using F20. 🙂
This time, I pick the same options on the create new Django project screen, and when I press forward, it says it’s installing 21 packages. Okay. It seems to be going, and I realize after wasting precious minutes of life reading crap on Twitter that it has been quite some time. I check back on the DevAssistant window – it looks like it’s still working, but it’s kind of not clear what it’s really doing.
Then I notice the tiny little dialog peering down at me from the extreme upper left corner of my laptop screen (it is easy to find in this screenshot; harder when other windows are open):

So this is another window positioning issue. I drag that little guy (who has some padding and alignment issues himself, but nothing earth-shattering) closer to the center of the screen so I can fill him out. The problem is, I’m not really sure of the context – why does it want my name? Does it just want my nickname, my first name, my full name, my IRC handle…? I end up typing ‘mairin’ and hit enter.

And then, something clicks. “I bet it wants my name and email address for the git config.” Well, crap. I already typed in “mairin,” and that’s not the name I want on my commits. I hit “Cancel” on the email dialog shown above, and try to “start over” by going back to the main window and creating the “Ponies” project again. But… ugh:

So there are a few problems here:

• The form field for my name lacked enough context for me to understand what information the software really wanted from me.
• I figured out what the software wanted from me too late – and there isn’t any way for me to go back and fix it via the user interface, as far as I can tell.
• There’s a transactional issue: in order to completely finish creating the project as I requested, DevAssistant needed some additional information. I bailed out of providing that information, leaving the project in an unknown state. (Will it work, and just miss the features that required information I didn’t provide? Since I bailed out early, which features will be missing? Is there a way to fix it by filling them in afterwards? Should I just delete from the filesystem and start over again?

The latter is what I did – I went into nautilus, nuked my ~/Code/Ponies directory, and ran through the Django project creation process (same options) from the main DevAssistant window one more time.
Unfortunately, it remembered the name I had given it. Normally this is a wonderful thing – interfaces that ask the same question of a user over and over again are annoying. In this instance, however, the politeness of remembering my name was a bit unforgiving – how could I correct my name now? Will all projects I create in the future using DevAssistant have “mairin” as my name instead of the “Máirín Duffy” of my vain desires??
Well, a rose by any other name would smell as sweet – whatever. Let’s carry on. So I am asked my GitHub password after my email address, which I provide, and soon afterwars I am greeted with a completed progress screen, a link to the project I created on GitHub, and a perusable log of everything DevAssistant just did:

So I think I’m done at this point? Maybe? I’m not 100% clear where to go from here. Some potential issues I’ll note at this point:

• The project I created on GitHub through this process is completely empty. I was expecting some Django-specific boilerplate content to be present in the repo by default, and maybe some of the files suggested by GitHub (README, LICENSE, .gitignore.) But maybe that part happens later?
• There’s an ssh issue in the logs. Ah. Now we see why my repo on GitHub is empty:
  
Problem pushing source code: ssh_askpass: exec(/usr/libexec/openssh/ssh-askpass): No such file or directory
Host key verification failed.
fatal: Could not read from remote repository.


I didn’t see a seahorse dialog pop up asking me to unlock my ssh key. I open up seahorse – it looks like DevAssistant made an RSA key for me. I’m not sure what’s going on here, then. It never asked me for a passphrase to create a new key.
I have an interesting test case in that I have a new laptop that I didn’t copy my real ssh key over to yet. I wonder how this would have gone done if I did have my real ssh key on this system…
Then, I get an email from GitHub:

The following SSH key was added to your account:
DevAssistant
98:a0:c9:9e:aa:44:08:ae:c4:96:a0:f9:1c:96:34:04
If you believe this key was added in error, you can remove the key and disable
access at the following location:
https://github.com/settings/ssh

If the new ssh key was added to my account, then why didn’t this work? :-/
My big question now is: what do I do next? Here is what I have:

• A new boilerplate Django project in my home directory.
• An empty GitHub project.
• Some stuff that got added to vim (how do I use it?)

What I don’t have that I was expecting:

• Some kind of button or link or something to the boilerplate code that was created locally with some tips / hints / tricks for how to work with it. (Links to tutorials? Open up some of the key files you start working with in that environment in tabs in Geany or Eclipse or some IDE? Okay so I selected vim – tell me how to open this up in vim?)
• Some acknowledgement of the ‘Ponies’ project I just created in the DevAssistant UI. I feel that my ponies have been forgotten. There isn’t any tab or space in the interface where I can view a list of projects I created using DevAssistant and manage them (e.g., like changing the ssh key or changing my name / email address associated with the project.)

I’m feeling a bit lost. Like when the lady in my GPS is telling me how to get to Manhattan and she stops talking to me somewhere in the Bronx.

Use Case 2: Create a new C project, using Eclipse as a code editor.

Back to the main window in DevAssistant! I click on the “C” button and right away am greeted with the “Create Project -> C” screen, which I dutifully fill out to indicate a desire to use Eclipse and to upload to GitHub:

A modal alert dialog ask me if it’s okay to install 139 packages (and again, helpfully offers a list of them if I want it.)
(The alignment within the dialog is a bit off; there’s a lot of extra padding on the bottom and the buttons are a bit high up. The OK button should probably be the right-most one, and a different widget used for ‘show packages,’ (like a disclosure triangle, maybe.)

First, I click to show the list of packages. Now I see why there is so much padding on the bottom of the dialog. 🙂 But it’s not enough space to comfortably skim the list of dependencies:

I drag out the window size to make it a bit bigger to more comfortably view the list. Some package names have a “1:” in front of them, some have “2:” in front of them, some have nothing in the front. I’m not sure why.

Anyway, enough playing around. I agree it’s okay to install the dependencies.
I watch the dialog. 139 packages is a lot of packages. While they are downloaded, there’s no progress bar or animation or anything to let me know that it’s still actively working and not crashed or otherwise unstable. The only indications I have are the cursor getting set to spinner mode when I go to the DevAssistant window, and the text, “Downloading Packages:” at the bottom of the visible log in the DevAssistant window:

After a little while, unfortunately, things didn’t go so well:

Here’s the full error log.
So now I’m not sure what state I’m left in. The “DevAssistant setup wizard” window has grayed out “Main window” and “Debug logs” buttons – the only live button is “Copy to clipboard.” I click on “x” in the upper right corner and it tries to quit but it doesn’t seem to do anything. Then I notice the large Java error popup window hidden behind my browser window:

Once I closed that window, the main DevAssistant wizard window changed, and I was able to get access to the main window and back buttons.
On to the next use case!

Use Case 3: Import a project I already have on my system that I have cloned from Github, and import it into Eclipse

All right, so what project should I import? I’m going to import my selinux-coloring-book repo. 🙂 This is a git repo I created on github and have synced locally. Let’s see if I can import it and open it in eclipse.
So I go back to the main DevAssistant setup wizard window and I click on the ‘Modify Project’ tab along the top (is this the right one to use? I’m not sure):

I’m not sure whether I should do “Eclipse Import” or “Github.” If I hover over the Github button, it says:

Subassistants of Github assistant provide various ways to work with Github repos. Available subassistants: Create Github repository.

While the first sentence of the description makes this seem like the right choice, the last sentence gives me the sense that the only thing this button can do is create a new github repo since that seems to be the only available subassistant (whatever a subassistant is.)
The Eclipse Import hover message is:

This assistant can import already created project into Eclipse. Just run it in the projects directory.

This seems like what I want, except the last line has me confused. I’m running a UI, so why is it telling to me to run something in a directory? (I’m assuming this is maybe a shared help text with a command-line client, so it wasn’t written with the GUI in mind?) Anyway, I’m going to go with the “Eclipse Import” button.
Again, the main DevAssistant window disappears and a new window pops up, ignoring my window placement of the first window and centering itself on top of my windows in the middle of my active screen. Here’s what that new window looks like:

So I notice a few issues on this screen (although note some of them may be because I’m not a real developer and I haven’t used Eclipse in years):

• There are two text fields where the user can specify a path on the file system. While such paths are usually pretty long, the fields aren’t wide enough to show much beyond the portion of my path that points to my home directory – /home/duffy. So these fields should probably be wider, given the length of these kinds of paths.
• I’m not sure what Deps-Only is going to do – what kind of project is it assuming I have? Is it going to somehow detect the dependencies (from make files?) and install them without importing the project? Why would I want to do that?
• The options are listed out with checkboxes – and you can click them all at once. Does that make sense to do? I guess it does – I could specify the Eclipse workspace directory (although is that in ~/workspace or $PROJECT-PATH/eclipse?), and the path to the project, and that I only want deps-only. It seems like maybe ‘deps-only’ is an option that is subject to path though – if I don’t specify a path, how is it going to detect deps?
• In fact, the process fails completely if I only select the “Deps-Only” checkbox and nothing else. So this selection shouldn’t be possible.

I end up just specifying my path (which points to /home/duffy/Repositories/selinux-coloring-book,) checking nothing else off, and clicking “run.” This doesn’t work – I get a blank “Log from current process” window that says “Failed” on the bottom:

On a whim, I check to make sure Eclipse is installed – yeah it is. That’s not the issue. I go back and check of the “Eclipse” checkbox in addition to the “Path” checkbox – looks like the failed C project creation made a ~/workspace directory, so I use that one. I hit run again…

I’m not sure where to go from here, so I’ll move on to the next use case.

Use Case 4: Begin working on an upstream project by locally cloning that project and creating a development environment around it

What upstream project should I work on? Let’s try something I don’t already have synced locally that isn’t too huge. I’ll choose fedora-tagger.
Okay back to the main DevAssistant window:

Where do I start? Not “Create Project,” because that’s for a new project. I look under “Prepare Environment:”

I’m not going to be working on DevAssistant or OpenStack, so I examine the hover text for “Custom Project:”

Only use this with projects whose upstream you trust, since the project can specify arbitrary custom commands that will run on your machine. The custom assistant sets up environment for developing custom project previously created with DevAssistant.

Hm. So two things here:

• This won’t work, because fedora-tagger wasn’t created with DevAssistant.
• I don’t think I would trust any project with this option, unless I could at least examine the commands it specified to run before running them. It would be nice to have a way to do that. Looking at the dialog linked to this button, it doesn’t look like there is.

Okay, so now what will I do? It doesn’t seem like there is a way to complete this use case under “Prepare Environment” unless my upstream is OpenStack or DevAssistant. The “Custom Task” tab won’t work, because the only option there is “Make Coffee.” So I’ll try to “Modify Project” tab:

Even though I know from an earlier use case that the hover text for the “Github” button seems to indicate that it can only create new Github projects, I try it. Nope, it just lets you create a new project. Hm. Well fedora-tagger is a python project. There’s a C/C++ projects button – maybe I should pick a C project instead.
So I’ll try a C project. What is written in C? I know a lot of GNOME stuff is written in C; I’m sure I could find something there. So I look at the tooltip on the C/C++ projects button:

This assistant will help you ito [sic] modify your C/C++ projects already created by devassistant. Avalaible [sic] subassistants: Adding header, Adding library

Well, I don’t know any GNOME C projects that were created with DevAssistant. :-/ At this point, I’m not sure how to move forward. I click on the “Get help…” link in the upper right:

It looks like doc.devassistant.org doesn’t work at all. Nor does devassistant.org …. it must be down. It’s still up on readthedocs.org though… okay let’s see:

Preparing: Custom – checkout a custom previously created project from SCM (git only so far) and install needed dependencies

This seems to be what I need? But the button for “Custom Project” said that the project should have been created with DevAssistant. Let’s try it anyway. 🙂 I’ll use gnome-hello, which is a small C demo project.

A couple things on this screen:

• All of the items are checkboxes, except for URL which has a red asterisk (‘*’) – why? Is that one required? Then it should probably have a checked and grayed checkbox?
• Again, the text fields for typically long path strings are pretty narrow.

I paste in the gnome-hello git url (git://git.gnome.org/gnome-hello) and hit “Run.”

Hmm, okay. So it didn’t find a .devassistant and bailed out. What did it do on my filesystem?

I would have preferred it not dump the git repo in my home dir – but I suppose that the path was an option I could have specified on the screen before. It might be better for me to be able to specify that I keep my git repos in ~/Repositories… so by default DevAssistant uses that so I don’t have to input it every time.
I don’t think there’s anything else I can do here, so I’ll finish here.

On to analysis!

In Part 2, we’ll go through the walkthrough and pull out all of the issues encountered, then sort them into different categories. Look for that post soon. 🙂