LearnWriting Error Messages, Navigation, and Documentation | Treehouse Show Ep 23


writes on January 15, 2013

In this episode of The Treehouse Show, Nick Pettit (@nickrp) and Jason Seifer (@jseifer) talk about Writing Error Messages, Navigation, and Documentation.

Here are the links for the week:

The 4 H’s of Writing Error Messages


Performance Calendar



BERG Cloud Buttons

Focal Point


Video Transcript

Nick: I’m Nick Petit.

Jason: I’m Jason Seifer.

Nick: And you’re watching The Treehouse Show, your weekly dose of
internets, where we talk about all things web design, web
development, and more.

Jason: In this episode we’ll be talking about error messages, the
usual dose of responsive design and our app review is Dash.

Nick: Let’s check it out. First up is the 4 H’s of writing error messages.
This is a really cool post, and let’s just get right into it.
The four H’s are: error messages need to be human, helpful,
humorous and humble. So, let’s just break each one of those down
really quick. What do we mean when we say “human”? Well, this
error message from Twitters says “Error unauthorized.” That
really doesn’t make a lot of sense. It doesn’t seem like it was
written for people, and actually it doesn’t even seem like it
would make sense to anyone but a developer.

Jason: It makes perfect sense to me.

Nick: Well, you’re a developer Jason, so of course it does.

Jason: But it’s on the lower end of the human scale.

Nick: The Firefox error message here is, of course, a better example where
they say “Well, this is embarrassing.” I mean, that’s something
that is conversational, something that people say in real life.
So next up is helpful. Is the error message actually helping the
person solve the problem? So, if something goes wrong in the
application, you know, does it help them make it right? You
know, if they entered bad data are you telling them “Hey, you
actually needed to enter this other thing”?

Jason: For example, if passwords didn’t match are you saying “The
passwords didn’t match” or “Couldn’t sign you up for the site”?

Nick: Exactly. That’s exactly right. Next up is humorous. So, when LastFM
goes down it’s always amusing, it says “Holy moly, we just blew
a fuse. Need. More. Amps.” You know, it’s pretty funny. I really
like this example from gMail as well. When you go ahead and type
in your username and you have, you know, too many periods or a
bunch of other different pieces of punctuation it says “Ah, a
fan of punctuation. Alas, usernames can’t have consecutive
periods.” So, pretty nifty. Last one is humble. Basically it’s
just saying that you should be apologetic when something goes
wrong, because oftentimes when something goes wrong in a piece
of software, the user will often feel like they caused the
problem. They’re like “Ah geez, I broke it. I must be stupid. I
must not know how to use this” when really it’s probably the

Jason: So you shouldn’t say “Error. This is probably your fault” is
what you’re saying there.

Nick: That’s pretty much it, Jason. You basically want to apologize to the
user and say “Oh, we’re sorry. Something went wrong. We’re going
to try to fix that as soon as we can.”

Jason: Oh, that’s legit.

Nick: Yeah.

Jason: Oh cool. Nice bunch of tips there.

Nick: Yep.

Jason: I thought it was going to be more along, you know, dodge-ball
tips, but whatever.

Nick: No, no. Not quite.

Jason: Next up we have a project called jhere. This is billed as “Maps
made easy.” This is a jQueary plug-in that provides a layer of
abstraction over the HereMaps API. So, there’s a bunch of
different things that you can do when working with the HereMaps
API and using this jQueary plug-in you get a very, very easy and
simple way of working with what can be a really complicated API.
Now, if you take a look at the documentation for jhere it’s very
simple and quick to include on your page and making a map is, I
mean, really easy. This is just a couple lines of code. Drop it
into your page and there’s different options that you can have
as well. Very, very simple to use, and yeah, check that out.
Jhere. It uses the HereMaps API which you don’t see a lot of
people using, but they do provide really good maps.

Nick: Pretty nifty. So next up is a blog post about front-end performance.
For those of you that are more advanced, this might be old news
but it’s always good to remind ourselves about techniques that
provide good front-end performance. So I won’t go through all of
these tips, but the first two talk about resource packaging and
using a single host name, so obviously you want to try to reduce
the number of resources that you have as much as possible and
try to reduce those http requests and serve them all on a single
host name. Another tip is to load Java Script asynchronously.
So, for example, you can go ahead and load in all of your html
and CSS and actually display something on the page that the user
can actually see and then in that split second after the page
loads you can go ahead and load in your Java Script and they
won’t really know the difference. It will appear as though the
page loaded very quickly when actually you’re still loading in
that functionality.

Jason: That’s something that I think is going to be a bit more useful
when you’ve got the plug-ins for saying “Hey, like us on
Facebook,” “Post this on Twitter.”

Nick: Exactly.

Jason: You know, load up your page first, then put in the social
buttons because that can slow a page down if you wait for
everything to load.

Nick: Especially, yeah, if you have a lot of social buttons and you just
want people to post your stuff all over the internet, then yeah,
it’s going to take a little while for all of those to load in.
So it’s good to do it asynchronously.

Jason: Nice.

Nick: Yep.

Jason: Next up is going to be our app review.

Nick: Let’s check it out.

Jason: Our app review this week is an app called Dash. Dash is a
simple OS10 application that is a snippet manager and
documentation browser. Now as we usually say, Dash is not
sponsoring the show. This is a paid application. Shame on them.
But this is incredibly useful. Here’s the Dash website right
here, but what it really lets you do is download your different
documentation and then you’ve got this one window where you have
all of your documentation on the left and then you can search
through everything. So, let’s say you wanted to get the jQueary
documentation for the AJAX method, you can just type in “.AJAX”
and it will very, very quickly filter through everything and
show you the matching methods in the documentation that it has
available. It also has options to Google the method you’re
looking for or search stack overflow. You can also set up a
shortcut key to launch Dash from anywhere and search, and then
you can even set up your own snippets, you know, if you have a
piece of code that you really like or grab it from the
clipboard, create a new snippet and you can search from that as
well. In addition to what it comes built in with, you can always
get more documentation. There is a ton of different options for
documentation and then you can also create your own using a
specific format that they have on the site. So this is a really
awesome application. I’ve just found it recently and I’ve been
using it basically nonstop. So, yeah, check that out. We’ll have
a link to that in the show notes. You can also get it in the Mac
App Store just searching for Dash.

Nick: No, I think it’s really cool, especially when you’re searching for a
particular method and you have lots of different Java Script
libraries installed, it might be good to go ahead and compare
methods maybe for the project that you’re working on, you don’t
actually need all the robustness of jQueary and you can say “Oh,
well this smaller library actually has the thing that I need
already” and I really like the code snippets feature to. It’s
good for organizing your code, especially over several years of

Jason: Yep.

Nick: Where you worked on a project, like, two years ago and you wrote this
really cool thing. It’s good to remember that that’s there and
you can go ahead and use that.

Jason: Oh, one other really nice feature, all the documentation works
offline, so you don’t have to be connected to the internet.

Nick: Well-

Jason: Yeah.

Nick: That’s good for when you’re coding on an airplane.

Jason: Exactly.

Nick: Although a lot of those have wifi now.

Jason: Which is the only time that I’m offline

Nick: Yeah. Next up is FooTable, and FooTable is a jQueary plug-in that
makes tables look really good at smaller, mobile screen sizes.

Jason: I thought it was pronounced Foot-able.

Nick: It’s actually not pronounced foot-able, it’s FooTable.

Jason: Okay.

Nick: Believe it or not. So, tables are notoriously bad on mobile screens,
basically when you re-size the browser or re-size your screen or
you’re looking at a mobile screen it tends to look pretty bad.
Tables tend to cause a lot of horizontal scrolling and they’re
just, it’s so much data that you want to display but it just
doesn’t fit on the screen. So that’s always been a challenge.
FooTable aims to solve that and they basically do it by hiding
some of the data. So, it hides certain columns at different
resolutions, which, in responsive web design we call break
points, and then the rows become expandable to show the data
that’s hidden, so you see these little plus and minus buttons
there. So if a user is looking at a particular piece of data and
they want to go ahead and learn more about that, they can click
on the little plus button and expand it. So, I think it’s a
pretty elegant solution for handling tables on mobile screens.

Jason: That’s awesome, really, really useful.

Nick: Yep. Pretty cool.

Jason: Next up we are going to talk about an article on CSS Tricks on
recreating the BERG Cloud Buttons using only CSS and html. So,
over on the CSS Tricks, also, no shame on them, they are a
sponsor of Treehouse. Shame on us for doing this shameless self-
promotion, but there’s some really cool buttons that they have
over on the BERG Cloud, and as they say in the article “The BERG
Cloud buttons are pretty sweet looking.” So, the article just
goes over how to recreate these kind of 3D-ish buttons with
backgrounds using just a little tiny bit of markup, and it goes
through, tells you how to use the CSS box shadow attribute and
different classes and then finally you can go and see the final
version over on a code pin link. Look at that. Look at that

Nick: Wow.

Jason: I know; incredible. It’s like we’re living in the future.

Nick: It’s amazing.

Jason: Using no images to create these buttons, pure CSS and html.

Nick: That’s awesome.

Jason: Yeah. Awesome post.

Nick: So next up is a blog post over on Design Shack, about a GitHub
project that I believe is called Focal Point. It allows for
intelligent cropping of responsive images. So what does that
mean? Well, basically when you normally re-size a responsive
design, the images will flex and scale, but sometimes images can
get so small that it’s hard to really see what is relevant in
the image, so instead this takes the approach of cropping the
image. Of course, the problem with that is that if you just kind
of crop and image randomly or, well, not randomly, but with the
normal focal point, you might cut out what’s actually important
in the image. It could be over on the right or the left or what
have you. This allows you to actually set a focal point for the
cropping. So, for each one of your images you basically can take
a grid, it looks like this, and you would have your normal focal
point which is in the middle, and you can move it up and to the
right, for example. Now, the code for this is done in a class
name that looks like this, so right three and up three, and
that’s going to go ahead and change the focal point for when an
image is cropped. So on the left here you can see this original
image and on the right you can see what it looks like when it’s
cropped. So it maintains what’s actually interesting about the
image when it gets cropped and flexed downward.

Jason: That’s amazing.

Nick: Yeah.

Jason: Not only is it a great idea for a plug-in, you know, CSS and
Java Script, but the site did an amazing explanation of it as
well. You know, those illustrations were extremely helpful.

Nick: Yeah, it’s actually a pretty complicated idea, but that does make it
really easy to understand. Pretty nifty.

Jason: Yeah. Next up we have a project called TinyNav.js. This is a
very small piece of Java Script that is also for responsive
design. It will take a navigation item that you have, say, you
know, an un-ordered list with a bunch of list items, and then on
a handheld device or when the screen shrinks to too small a
size, it will replace your navigation with a select drop down
with the same attributes as those links. Also, if you are on a
current page, it will actually put that one as the selected
attribute. Now you may be saying to yourself “Hey, a lot of
these plug-ins exist out there already. Why would I use this
one?” Well, the main advantage of TinyNav.js is that it’s small.
It’s only 443 bytes minified and g-zipped.

Nick: Wow.

Jason: I know. That’s tiny.

Nick: It is.

Jason: That’s probably where they got the name, TinyNav.js.

Nick: TinyNav, yeah.

Jason: So I guess that makes sense. Man.

Nick: Yeah.

Jason: Anyway, yeah, there’s a few options that you can go through,
including adding styles and it’s a pretty easy, pretty simple
plug-in. So, check that one out. That works all the way down to

Nick: Wow.

Jason: I know.

Nick: That’s amazing.

Jason: It is.

Nick: So Jason, what did we learn today?

Jason: I think we learned that hair grows back.

Nick: It does.

Jason: And we’re all happy about that.

Nick: Yep. Feeling pretty good. I am @nickrp on Twitter.

Jason: And I am @jseifer. Thanks so much for tuning into this episode
of the Treehouse Show. For show notes or more information on
anything that we talked about, check out our Youtube channel at

Nick: And of course if you’d like to see more videos like this one and
learn about web design, web development, mobile development or
starting a business, be sure to check us out at
teamtreehouse.com. Thanks so much for watching and we’ll see you
next week.

Announcer: If you’d like to see more advanced videos and tutorials like
this one, go to teamtreehouse.com and start learning for free.


Learning with Treehouse for only 30 minutes a day can teach you the skills needed to land the job that you've been dreaming about.

Get Started

Leave a Reply

You must be logged in to post a comment.

man working on his laptop

Are you ready to start learning?

Learning with Treehouse for only 30 minutes a day can teach you the skills needed to land the job that you've been dreaming about.

Start a Free Trial
woman working on her laptop