Greg Boone


Tag: usability

Content design and education

A couple friends of mine work as teachers here in Denver (by the way, we made it to Denver!) and we recently started talking about design in education. One friend told me he proposed some design standards for his fellow teachers. The problem he was trying to solve was relatively simple: Each teacher makes a Moodle site for each class, the designs of those pages vary wildly and result in a mostly confusing education experience for students.

I’m not a teacher (anymore), but my friend’s school-wide standards idea got me thinking: We do a lot of this kind of thing at 18F. What are some ways our approach to solving design problems might apply in education?

The problem of design

Slate’s Dan Kois recently articulated one version of this problem on Slate’s “Mom and Dad are Fighting” podcast. Kois described a “parenting fail” (around the 3:50 mark). His kid missed an assignment because the due date was not in the learning management system but in Google Classroom (and this was, apparently, not obvious). He fired off an angry missive to the teacher. On the show he said his initial reaction was:

What the fuck is Google Classroom? … [And] why have we gone from homework in one fucking place my kid doesn’t remember to look at to contradictory instructions in two fucking places my kid doesn’t remember to look at?

Kois admits taking out his frustration on the teacher was wrong — hence the fail.

In all likelihood part of the problem is that the first system was either a garbage fire of user experience (for the teacher, too, no doubt) or didn’t provide the teacher enough flexibility to organize the assignments. Or both. Needing a more robust platform, they turned to Google Classroom. None of that is the teacher’s fault, but is there something the teacher, or the school, could do to prevent confusion like that? Here are a few steps to take to build learner-centered class webpages.

1. Talk to students.

Start with understanding what the students need. Find an opportunity to watch students navigate their daily homework routine and think aloud while they do it. Pay attention to what they’re saying, where they’re making mistakes and strategies they use to correct them. You might even record them. Then design the page for your students.

This is a classic format for usability studies, and even asking five students can lead to insights that improve the experience for all.

2. Adopt school- or district-wide standards

Consistency across common elements like link color, typography, buttons, and information architecture can save a student time and energy by instantly recognizing them across each of their classes. That’s time and energy they now have for being successful. Consistency across the district means less re-learning when they move schools. Plus it makes it easier for teachers new and old to develop new classes without repeating these routine decisions.

The National Parks have a common standard that lets people instantly recognize and trust park resources, rangers, and informational materials no matter which park they’re at. The same could be done for schools or even districts. Resources like WebAIM and content guides (shameless plug) can help ensure your standards are accessible to all students. Make sure to test these standards with real students, while you’re making them, too.

3. Design for the student

Travis Grandy, a PhD student in Composition and Rhetoric at UMass, recently wrote about ways to improve his syllabus after realizing many of his students weren’t reading it. Grandy’s tips are great and the same basic concepts could apply to a course website or any document given to a student. He redesigned his syllabus because:

Even with a thorough … syllabus, I still had to respond to the same student questions over and over again, and … I felt my course needed a larger narrative that unified learning outcomes with course requirements, and expectations about the day-to-day work students do in my class.

After redesigning, he recommends periodically re-checking the designs every once in a while.

Your class speaks for itself

Again, I’m not a teacher, but like any artifact, your course website is an expression of your course goals and an expression of you. These are a few tools you can use to figure out how to balance those interests. Kois loves his kid’s school, he says so on his podcast. His frustration rose out of uncertainty over whether his kid was as successful as they could be. It was probably a great assignment, well designed and supported by the teacher’s expertise. Why risk students not being able to complete it properly?

GitHub for Mac: A Usability Review

Update: This post is out of date. The new GitHub Desktop App has major improvements to many of the usability problems addressed here. The GitHub For Mac app described below is no longer distributed.

Since first learning how to use Git a couple years ago I’ve been pretty convinced that using the command line is the only way to go. Partly it’s simplifying my workflow: On a given day I have Terminal open for running tests, working with Jekyll, and quick editing in vim; a browser open to work with GitHub, inspect my work, and debug things; plus a text editor for All the Things. A Git client is one more application running that I have to integrate into a three screen, multiple tab workflow.

I tried GitHub for Mac a few years ago when I was first learning Git. I thought I’d be able to focus on the code without worrying about the version control part of my job. I don’t remember why I went command line only, but I think it had something to do with my first pull request at CFPB: one that had every file in the repo committed as “changed” because at some point I had changed permissions on the whole repo but forgot to tell Git to ignore that crap. OOPS!

Being a full-time developer working with primarily with other developers for a year-and-a-half is a good way to forget what you didn’t know before you started. So I dusted off the ol’ GitHub for Mac app, and decided to evaluate it again. I work with a few people who are where I was two years ago and I am trying to make a conscious effort to check assumptions about what is “obvious” or “easier.”

GitHub for Mac

The flagship desktop app made by GitHub for folks who use the company’s web service, this app has the huge advantage of being free and integrated with your GitHub account. One of the first things you have to do with GH for Mac is sign in to your GitHub account and it automatically creates and pairs an SSH key with your Mac (or uses an existing one). This Git Client changes around some terminology that might be familiar to Git power users. The biggest change is the “Sync” feature that both pulls down local changes and pushes your changes.

The GitHub for Mac interface with the Sync button highlighted

The main view on the application is essentially a visual representation of git status. Each changed file fills in as they are modified with a checkbox. Checking the box (done by default) presumably runs git add on the file, and at the botton of the center column is the “Commit and Sync” button. When pressed, this button makes a commit locally and immediately pushes the branch to the remote whence it was cloned. If you don’t enter a commit message, the button triggers an alert asking you to include one.

To the right of this center column is a live diff. Your local changes against what was already there.

A git diff view of GitHub for Mac

You can unstage a file (git reset HEAD <file>) by simply unchecking the box. This will keep it from being committed when you “Commit and Sync.”

Once you commit there’s an undo button to roll back your changes.

An undo button! We've all wanted one of those at one point or another.

You can even make a pull request right from the app. And it will even tell you if there aren’t any commits to merge.

Immediately there are a few things to love about this interface. Issuing pull requests without going to is a dream. It’s like click, clack-clack-clack, click and :boom: pull request.

The visual diff is also handy and maybe a new feature from when I first used the app a couple years ago. It certainly makes you wonder what has changed if the diff looks empty.

GitHub for Mac, like any GUI, is a graphical overlay applied on top of an otherwise complex system. To that end, Nielsen’s Heuristics can be a good way of evaluating the design. Those heuristics are:

  1. Visibility of system status
  2. Match between system and the real world
  3. User control and freedom
  4. Consistency and standards
  5. Error prevention
  6. Recognition rather than recall
  7. Flexibility and efficiency of use
  8. Aesthetic and minimalist design
  9. Help users recognize, diagnose, and recover from errors
  10. Help and documentation

Git is already pretty terrible at a few of these, particularly numbers 2, 4, 5, 6, and 9. But it nails a few, including 1, 3, 7, and 10. The question at hand, though, is how does GitHub for Mac do?

Visibility of System Status

GitHub for Mac comes out pretty well here, though it could do better. Many complicated workflows are compressed into a single button press and when this works well it really works. The main view, for example shows git status and git diff live. It also lets you toggle to other views like “History” and “Branches.” That makes the non-exclusive list of Git commands you can accomplish within one click of opening the app:

  1. git add
  2. git commit
  3. git push
  4. git pull
  5. git branch
  6. git status
  7. git reset HEAD <file>
  8. git log
  9. git branch
  10. git checkout <branch>
  11. git checkout -b <new-branch>

These commands are packaged up into buttons like “commit and sync” that encompasses a multi-step workflow. At its simplest it looks like this:

git pull origin master
git commit
git push origin master

Masking those parts of the system comes at the expense of the user knowing what all is happening when that button is clicked. This was most painfully obvious when pre-commit hooks were introduced to my workflow.

Hooks, in Git, are small programs that run at different stages in the workflow. If you’re curious I recommend reading up on them in the Git Book. One common place for a commit hook to run is “pre-commit” to stop developers from committing things like passwords, or easily detectable security problems. I wrote one to optimize images in a specific folder. GitHub for Mac still runs the hooks at the appropriate times, it just does so invisibly. Instead of showing the action, it looks like the application is hanging.

By abstracting git add actions into checkboxes, the app conceals a lot of the work that Git does to track and record changes. But maybe that’s a good thing. It took me a while before I realized you had to run git add again if I changed a file after I did it the first time but before I committed. As a beginner, I thought I should only have to do it once. With GitHub for Mac that expectation is true. The box is already checked, and the app re-adds the file to the commit for you, this leads well into the second heuristic.

Match Between System and the Real World

Git has a lot of bad idioms. The command git commit feels a lot like the “save” command in any other application but what most beginners don’t learn is that git add is closer to save. Running commit is more like finishing a draft while git add is like every command-s you issue while you’re writing.

It is also quite difficult to explain the three “states” a file can be in when working in a git project to those who have no experience with it. What do the terms ‘tracked’ and ‘untracked’ mean to somebody who has only worked with Microsoft Word? What if something is Staged for Commit? How is being “tracked” different from being “staged?” GitHub for Mac answers these questions by saying it doesn’t really matter and then mapping the concepts of Git onto the metaphors we already have for working with computers. Persistently re-adding the file for you? That’s autosave. “Commit and sync,” that’s finishing a draft and backing it up to Dropbox.

There are a few times this falls down. For example, what does this mean?

WTF does the partially checked box mean? My autosaves!

Command line Git would have an answer with git status. It’s a little harder to tell at a glance what is happening in GitHub for Mac.

In addition, you’re rarely working on a Git project and not using another application. It would be great if GitHub for Mac were better integrated with a text editor or the file system. The app shows you which files were changed, but it’s not clear from just looking at the app what you’re supposed to do with that information other than “sync and commit.” It’s hard to even figure out where the repo is, what other files are in it, and how to go about making more changes without the assist of another app. It turns out that right (or control, or two-finger, or force) clicking on the name of the repo will give you options including “Open in Finder” and “Open in Atom.” It’s unclear what happens if you don’t have Atom installed.

I’m not sure how many people would intuitively right click on the name of the repo in order to edit one of the files and would expect, instead, someone unfamiliar with GitHub would probably ask “what do I do now?” when they see the empty “Changes” tab. Since GitHub makes Atom, I suppose we can hope that future versions of GitHub for Mac will integrate some basic file editing features from Atom. In the meantime, I expect people unfamiliar with GitHub will remain confused about what they’re supposed to do with this app other than “Commit and Sync.” More cues about how to find and edit files in the repo would help.

User Control and Freedom

Command line Git has this down and GitHub for Mac takes a lot of freedoms away by abstracting them into buttons (as discussed above). There are so many different workflows available to Git users, and for each one there is a camp of people who firmly, militantly believe they are doing it the right way. Rebasing vs. merging, forks vs. branches, when to branch vs. pushing to master, how frequently you should commit: these are all examples of different basic workflows that power users can expend a lot of hot air arguing about. (Guilty.)

GitHub for Mac resolves a lot of those issues by setting some smart defaults and removing some options. You can’t squash commits in the app (at least not easily). You can’t fetch from your remote without also merging in the latest changes. You can’t rebase, instead of merging, one branch into another. You can’t commit without also pushing your branch.

For those of us weaned on CLI Git this is an inexcusable restriction on our freedom and control over our projects. For others it is the enforcement of standards in an otherwise anarchical world.

Consistency and Standards

GitHub for Mac nails it. Where there might be multiple ways to accomplish a task from the command line, there is either one way to do it, or it is impossible from the app. This, I imagine, is a huge win for people new to Git. Unless, of course, the standards the app tries to enforce are different from the ones your team is using. There are a lot of ways to encourage patterns on top of Git, (aliases, hooks, good training) few of them are available in GitHub for Mac.

Some of the standards it enforces are huge improvements over conventional wisdom given to newcomers. Committing in the app, for example, requires and nudges users toward more informative commit messages. Let’s be honest and admit that someone who is new to Git and the command line probably isn’t very familiar with command line editors and crazy looking commands. To solve that, or maybe to simplify the process, many Git tutorials recommend the shorthand git commit -m 'message'. This would be fine if that shorthand didn’t often lead to unhelpful messages like “fixed stuff”. (Again, guilty.)

A message like that is fine if the “stuff” is one change to one line of code but GitHub is collaborative, and commit messages should help your collaborators understand what changes you made. GitHub for Mac helps newcomers get past -m by providing “Summary” and “description” sections in the commit view. It’d be interesting to see data around whether GitHub app users provide more useful commit messages because of this nudge.

GitHub for Mac will not let you commit without a commit message and encourages a summary and description in each message

Flexibility and Efficiency of Use

This, again, is a mixed bag for the app. CLI Git is full of flexibility, as mentioned in the user control and freedom section, there are many different ways of accomplishing the same task in Git. To get the latest changes on, for example, your workflow might be as simple as:

git pull

Unless you’re working in a branch then it might be:

git checkout master
git pull
git checkout <your-branch>
git merge master

And if you’re on a fork it might be

git checkout master
git pull origin master
git push fork master
git checkout <your-branch>
git merge master
git push fork <your-branch> # (arguably optional)

And if you’re into rebasing instead of merging it’s a whole other can of worms.

Getting that kind of flexibility is maybe possible in GitHub for Mac, but obviated by default behaviors.

Finally, it’s worth mentioning here the ease of integration with GitHub’s web service. Issuing pull requests with the click of a button is a dream.

Issuing a pull request without going to

But the efficiency of issuing that pull request is halted by not being able to comment on or further interact with pull requests and issues without going to in your browser.

Aesthetic and minimalist design

This criterion has been touched on by others above, but the look and simplicity of the app cannot be ignored. I mentioned in the visibility of system status section that there are at least 11 git commands executable within one click of launching the app. In addition, the app abstracts away many of the more complicated commands into their most useful presentation. The “History” button takes you to a view that represents git log --date=relative with a git diff of that commit next in the opposite frame. You can even expand each commit and jump through the diff file by file.

The branch view defaults to git branch -v alongside a “Published” button, which, when disabled means you have pushed all possible changes.

All of this happens in relatively few clicks compared to how many commands and defaults you would need to have this kind of view in even the most sophisticated of command line set ups. These design choices give you the most valuable information about each commit formatted and displayed accessibly.

A couple things are confusing in this setup.

Moving the mouse to the left side of a branch turns the cursor into a hand and you can click and drag the branch. What exactly happens when you drag one on top of another is not intuitive. Are you switching branches? Merging one into the other? The answer is unclear without either giving it a shot and hoping you don’t make a mistake (see below) or looking it up.

There’s also a star button on the right side of a branch’s container. What this does is completely unclear. Clicking a star of an inactive branch appears to checkout or, “switch to,” in the language of the app, that branch. In fact, clicking on anything on an inactive branch appears to activate it, not just the “Switch to this Branch” item in the list that drops down from the “arrow down” button.

Finally, you can “unpublish” a branch. As an experienced git user this doesn’t mean much to me. Does it mean somehow reverting the remote branch back to the last previous push? Or, more likely, does it mean completely deleting the branch from the remote? It turns out it’s the latter, and any collaborators working on that branch will need to find another way of getting any updates since their last “sync.” To be fair, the app warns you about this when you attempt to unpublish.

The unpublish button warns you that your branch will be deleted from the remote repository.

Help users recognize, diagnose, and recover from errors

The “unpublish” feature is a good example of how GitHub for Mac fails to help users prevent and troubleshoot errors. If you’re a collaborator on a project and need to “revert” some changes you pushed to a branch, you might think “unpublishing” is your tool: and you would be wrong and the app gives you no indication of how to accomplish this. (To be fair, Git makes this intentionally difficult.)

Additionally, the warning message is inaccurate. An “unpublished” branch can be “republished” by pushing it back again. Maybe GitHub for Mac doesn’t let you do this, but in theory it is possible, just not by hitting Undo.

It is good that the warning is there, though. If multiple individuals are working off the same branch, revoking that branch is potentially confusing if not dangerous. And if you are new to Git, you might not know that “the remote repository” means and that by “unpublishing” you’ve just prevented your collaborators from accessing your work.

On another topic of branching and merging, GitHub for Mac might have made switching branches too easy. An accidental click on the Branches view might inadvertently cause you to commit to the wrong branch before switching back. Depending on the project, this could result in wild instability. At 18f, for example, accidental commits to staging will result in republication of our staging site – a complete obfuscation of our publishing process and contribution guidelines.

This is not to say that accidental commits to a branch can’t happen in command line git, but the GitHub for Mac app doesn’t make it easy to see errors as they occur and understand how to recover from them. The command line forces you to be more explicit by requiring you tell it exactly what branch you want, and what you want to do with it.

As far as diagnosing and recovering from errors, the app doesn’t help much with that either. In the above example, you would at no point get any indication you were making a mistake, how you got there in the first place, or what to do to fix it. If you committed and synced a load of changes to branch-a and another collaborator asked you to submit them to branch-b instead, you might know what that means, but you might not know how to solve it other than checking out a new branch and copying and pasting your final changes over manually. If you’re working with several files this could take a long time.

Help and documentation

In that last example, the easiest way to get out of that jam would be to merge or, better, rebase your branch-a onto branch-b like git rebase branch-a branch-b and then pushing up branch-b. If you only need some of the commits from branch-a you can do an interactive merge or, what I do, use git cherry-pick to extract the specific commits or range of commits from branch-a that are needed in branch-b.

Git is an incredibly well documented piece of software through guides like ProGit, tutorials from GitHub and Atlassian, and, shameless plug, 18F’s tutorial. There are separate man pages for Git and each subcommand (from the CLI, run man git-commit). And there are millions of Git users around the world answering questions on StackExchange ready for you to find by Googling your problem. If you’re at a software company, there’s a good chance someone on your team can help, too.

Little of that will be helpful on GitHub for Mac. The top search result for our merging problem above is to rebase --onto and the other top-voted answers recommend cherry-picking. If you’re using GitHub for Mac without knowing how to Git from the command line, what are you supposed to do?


GitHub for Mac is definitely a well-designed step in the right direction. For those new to Git or only working with repositories occasionally, it may be very useful and certainly an easier learning curve than learning how to use the command line and all of Git’s complexities.

It has a lot of room to grow, though. An app like GitHub for Mac could be a stand in for a user interface for static sites if it had built-in text editor and visualization of the repository’s tree. Or it could compete with a program like Tower if it offered more flexibility of use and workflow that a power Git user would want and a more exhaustive GitHub integration. At the moment, it feels like the app is struggling to figure out what it should be.

I work with a few people who had never used Git, the command line, or a static site generator before. Right now we’re trying to start people off at the command line and offer help as needed. We do this, in part, to standardize the way we work, but also because we think eventually all of us will encounter some kind of error GitHub for Mac won’t be able to solve and a more experienced Git user will have to intervene anyway.

Our hypothesis is that learning the command line from the start will help people feel more comfortable making mistakes and recovering from them. That means introducing people to a pretty steep learning curve. A lot of people believe the promise of a GUI is that it will reduce the learning curve. In this case, I’m not sure that’s true, at least not yet.

Comment on this post at

Dark Pattern Alert: Forced continuity at Blue Apron

This post is likely very out of date. I’ve been told Blue Apron has made improvements to their account closure process. This post is an historical representation of how they handled user requests in 2014.

A friend of ours gave us an awesome wedding gift: a week of free meals from Blue Apron. We’d recently tried out Relay Foods a similar but only tangentially competitive service of home grocery delivery. The key difference between Relay and Blue Apron is in the former you shop like you’re at a grocery store, the latter you’re delivered exact fixings for specific meals. Our first week of meals arrives Friday and we’re pretty excited to have at least three dinners next week under delicious control. Thanks Laura!

The service is great but from a usability perspective the process of redeeming this gift was interesting. One of the first things Blue Apron asked us for was a credit card number. Strange, we thought, because the gift covered the entirety of a week’s basic delivery (3 meals in one week). Tried as we might, we could not figure out how to redeem the gift without attaching a credit card to our account so, not wanting to turn down the gift, we did. We were then taken to a screen asking us how many nights per week we wanted meals still without any real indication of what the gift covered. The default was 3 meals per week so we figured we’d go with that and go up if the gift was for more. We clicked through and only then (3 screens later) were we aware of how many meals were covered by the gift. Even at that point, though, we still had no idea what we were actually getting only that it would be determined based on our “preferences.” So, seeking out the menus we had subscribed to, we clicked through to the “My Account Screen” to discover that we had been subscribed to automatic weekly delivery of three meals per week through to the middle of October.

Scheduled deliveries every week? We never ordered that!

Scheduled deliveries every week? We never ordered that!

At that point we freaked out a bit. If we asked for a weekly delivery of three meals, we certainly didn’t remember doing it. Clicking through the application we tried to find a link to disable the account but the closest we could find was the ability to skip a week’s delivery. Not even on the My Account page was there an option to cancel the account or halt deliveries. We went ahead and skipped the remainder of the meals and will be investigating how to stop the service altogether following our Friday delivery.

Forced continuity is a common dark pattern where users are automatically enrolled in a continual subscription after signing up for a free trial and was recently made illegal in the UK. It is particularly common with credit monitoring and media streaming services. The user signs up for a free month of credit reporting and suddenly, two or three months later notices charges on their credit card.. While most people signing up for Blue Apron are probably doing so because they want continual delivery of meals, the service should consider letting people sign up without a credit card or on a one-off transaction in order to redeem gift cards. At the very least, Blue Apron should allow its users to select 0 as an option along side 2 and 4 people on the “Edit My Plan” view with the understanding that ordering food for 0 people means $0 will be charged to a credit card.

Blue apron should give users a means to cancel or indefinitely pause service.

Blue apron should give users a means to cancel or indefinitely pause service.

Canceling Blue Apron service can be accomplished by emailing before your weekly cutoff. There does not appear to be any way of maintaining an account without being auto-enrolled in meal delivery. Finding this information requires three clicks, two page loads (in addition to loading, and some sleuthing. Scroll all the way to the bottom of any Blue Apron page and click “Contact & Help,” then choose “Skipping or Canceling” and click “Cancel my Account.” From there you’re taken to another page instructing you to send the email. Other help pages suggest there is no minimum subscription or commitment which, while true, is somewhat deceptive and a “roach motel” design anti-pattern.

We’ll update here with more on the cancellation process.