I have to say I was pretty impressed by how easy it was to set it up. Although I did have several small problems, most of them were less related to Cherokee itself, and more related to me not being very familiar with Node application configuration outside of Joyent’s environment, or FastCGI configuration. In particular, the web-based configuration is brilliant: you don’t have to open or know the format of any configuration files, but instead configure everything from a pretty powerful UI (which in the end writes a text configuration file of course, so you can always automate or generate the configuration if you need to). I even knew this already, but seeing it in action was pretty impressive. To avoid security problems with people accessing that configuration interface, there’s this little tool called cherokee-admin that starts another web server with the configuration interface (tip: pass the -b option without parameters if you want to connect to it from a different machine, which is the case unless you’re installing Cherokee in your own PC). On start it generates a random admin password, which you use to login.

Static content serving, CGI, FastCGI, specifying certain error codes for certain paths, and reverse proxying was all very easy to set up. There was only a small problem I bumped into: tweaking URLs in reverse-proxied responses. In my situation, I was doing reverse proxying from port 443 to port 3000. As the final application didn’t know about the proxy, it generated URL redirections to “http://…:3000/” instead of “https://…/”, so part of the process of proxying was fixing those URLs. Cherokee, of course, supports this out of the box, in a section called “URL Rewriting”. Each entry in that section takes a regular expression and a substitution string. My first attempt (“http://example.com:3000/” -> “https://example.com/”) didn’t work: all URL redirections were changed to “https://example.com/”, disregarding the rest of the URL. After some time trying different things, I decided to try with “http://example.com:3000/(.*)” and “https://example.com/$1″. As it turns out, that worked like a charm! The documentation does mention that it uses Perl-compatible regular expressions, but I thought the HTTP reverse proxy documentation could have been more explicit in this regard.

But apart from that detail, everything was very smooth and I’m very, very happy with it :-)

If you need any introduction you should really read the first part. I’ll just present the other three ideas I wanted to cover.

Focusing on common cases

This consists of testing only/mostly common cases. These tests rarely fail and give a false sense of security. Thus, tests are better when they also include less common cases, as they’re much more likely to break inadvertently. Common cases not only break far less often, but will probably be caught reasonably fast once someone tries to use the buggy code, so testing them has comparatively less value than testing less common cases.

The best example I found was in the wrap_string tests. The relevant example was adding the string “A test of string wrapping…”, which wraps not to two lines, but three (the wrapping is done only on spaces, so “wrapping…” is taken as a single unit; in this sense, my test case could have been clearer and use a very long word, instead of a word followed by ellipsis). Most of the cases we’ll deal with will simply wrap a given word in two lines, but wrapping in three must work, too, and it’s much more likely to break if we decide to refactor or rewrite the code in that function, with the intention to keep the functionality intact.

See other examples of this in aa20bce (no tests with more than one consecutive newline, no tests with lines of only non-printable characters), b248b3f (no tests with just dots, no valid cases with more than one consecutive slash, no invalid cases with content other than slashes), 5e771ab (no directories or hidden files), f8ecac5 (invalid hex characters don’t fail, but produce strange behaviour instead; this test actually discovered a bug), 7856643 (broken escaped content) and 87e9f89 (trailing garbage).

Not trying to make the tests fail

This is related to the previous one, but the emphasis is on trying to choose tests that we think will fail (either now or in the future). My impression is that people often fail to do this because they are trying to prove that the code works, which misses the point of testing. The point is trying to prove the code doesn’t work. And hope that you fail at it, if you will.

The only example I could find was in the strcasecmpend tests. Note how there’s a test that checks that the last three characters of string “abcDEf” (ie. “DEf”) is less than “deg” when compared case-insensitively. That’s almost pointless, because if we made that same comparison case-sensitively (in other words, if the “case” part of the function breaks) the test still passes! Thus it’s much better to compare the strings ”abcdef” and “Deg”.

Addendum: trying to cover all cases in the tests

There’s another problem I wanted to mention. I have seen several times before, although not in the Tor tests. The problem is making complicated tests that try to cover many/all cases. This seems to stem from the idea that having more test cases is good by itself, when actually more tests are only useful when they increase the chances to catch bugs. For example, if you write tests for a “sum” function and you’re already testing [5, 6, 3, 7], it’s probably pointless to add a test for [1, 4, 6, 5]. A test that would increase the chances of catching bugs would probably look more like [-4, 0, 4, 5.6] or [].

So what’s wrong with having more tests than necessary? The problem is they make the test suite slower, harder to understand at a glance and harder to review. If they don’t contribute anything to the chance of catching bugs anyway, why pay that price? But the biggest problem is when we try to cover so many test cases than the code produces the test data. In this cases, we have all the above problems, plus that the test suite becomes almost as complex as production code. Such tests become much easier to introduce bugs in, harder to follow the flow of, etc. The tests are our safety net, so we should be fairly sure that they work as expected.

And that’s the end of the tips. I hope they were useful :-)

These ideas are presented in no particular order. Each of them has a brief explanation, a concrete example from the Tor tests, and, if applicable, pointers to other commits that illustrate the same idea. Before you read on, let me explicitly acknowledge that (1) I know that many people know these principles, but writing about them is a nice reminder; and (2) I’m fully aware that sometimes I need that reminder, too.

Edit:  see the second part of this blog.

Tests as spec

Tests are more useful if they can show how the code is supposed to behave, including safeguarding against future misunderstandings. Thus, it doesn’t matter if you know the current implementation will pass those tests or that those test cases won’t add more or different “edge” cases. If those test cases show better how the code behaves (and/or could catch errors if you rewrite the code from scratch with a different design), they’re good to have around.

I think the clearest example were the tests for the eat_whitespace* functions. Two of those functions end in _no_nl, and they only eat initial whitespace (except newlines). The other two functions eat initial whitespace, including newlines… but also eat comments. The tests from line 2280 on are clearly targeted at the second group, as they don’t really represent an interesting use case for the first. However, without those tests, a future maintainer could have thought that the _no_nl functions were supposed to eat whitespace too, and break the code. That produces confusing errors and bugs, which in turn make people fear touching the code.

See other examples in commits b7b3b99 (escaped ‘%’, negative numbers, %i format string), 618836b (should an empty string be found at the beginning, or not found at all? does “\n” count as beginning of a line? can “\n” be found by itself? what about a string that expands more than one line? what about a line including the “\n”, with and without the haystack having the “\n” at the end?), 63b018ee (how are errors handled? what happens when a %s gets part of a number?), 2210f18 (is a newline only \r\n or \n, or any combination or \r and \n?) and 46bbf6c (check that all non-printable characters are escaped in octal, even if they were originally in hex; check that characters in octal/hex, when they’re printable, appear directly and not in octal).

Testing boundaries

Boundaries of different kinds are a typical source of bugs, and thus are among the best points of testing we have. It’s also good to test both sides of the boundaries, both as an example and because bugs can appear on both sides (and not necessarily at once!).

The best example are the tor_strtok_r_impl tests (a function that is supposed to be compatible with strtok_r, that is, it chops a given string into “tokens”, separated by one of the given separator characters). In fact, these extra tests discovered an actual bug in the implementation (ie. an incompatibility with strtok_r). Those extra tests asked a couple of interesting questions, including “when a string ends in the token separator, is there an empty token in the end?” in the “howdy!” example. This test can also be considered valuable as in “tests as spec”, if you consider that the answer to be above question is not obvious and both answers could be considered correct.

See other examples in commits 5740e0f (checking if tor_snprintf correctly counts the number of bytes, as opposed the characters, when calculating if something can fit in a string; also note my embarrassing mistake of testing snprintf, and not tor_snprintf, later in the same commit), 46bbf6c (check that character 21 doesn’t make a difference, but 20 does) and 725d6ef (testing 129 is very good, but even better with 128—or, in this case, 7 and 8).

Testing implementation details

Testing implementation details tends to be a bad idea. You can usually argue you’re testing implementation details if you’re not getting the test information from the APIs provided by whatever you’re testing. For example, if you test some API that inserts data in a database by checking the database directly, or if you test the result of a method call was correct by checking the object’s internals or calling protected/private methods. There are two reasons why this is a bad idea: first, the more implementation details you tests depend on, the less implementation details you can change without breaking your tests; second, your tests are typically less readable because they’re cluttered with details, instead of meaningful code.

The only example I encountered of this in Tor were the compression tests. In this case it wasn’t a big deal, really, but I have seen this before in much worse situations and I feel this illustrates the point well enough. The problem with that deleted line is that it’s not clear what’s it’s purpose (it needs a comment), plus it uses a magic number, meaning if someone ever changes that number by mistake, it’s not obvious if the problem is the code or the test. Besides, we are already checking that the magic number is correct, by calling the detect_compression_method. Thus, the deleted memcmp doesn’t add any value, and makes our tests harder to read. Verdict: delete!

I hope you liked the examples so far. My next post will contain the second half of the tips.

Introduction

How valuable are UI design guidelines depends on who applies them. They often describe goals, not actions, so they can’t be followed like a recipe. They also often conflict with each other. This book tries to give rationale to make them easier to apply.

Visual content

• Structure: Gestalt principles (proximity, similarity, continuity, closure, symmetry, figure/ground, common fate), see on p. 11-22. They act together, and sometimes they produce effects we don’t want: review designs with each of these principles in mind to see if they suggest a relationship that shouldn’t be there.
• Text: we’re wired for language, but not for reading. Typical text-related mistakes: geek-speak, tiny fonts (if the text is hard to read, it probably won’t be read, so you might as well remove it), burying important information in repetition, and using just too much text (use just enough to help most users get to their intended goals).
• Colour: our vision is optimised to detect contrasts (edges), and our ability to distinguish colours depends on how they are presented (colours are harder to distinguish if they’re pale, in small/thin patches or separated from each other). Guidelines for colour: (1) distinguish by saturation/brightness, not only hue, (2) use distinctive colours (red, green, yellow, blue, black and white), (3) avoid colour pairs that colour-blinds can’t distinguish (tips on p.59-60, including http://www.vischeck.com/), (4) don’t rely on colour alone, and (5) don’t place strong opponent colours next to each other (see p. 62).
• Peripheral vision: we only have good resolution in the centre of wherever we’re looking. Peripheral vision (1-2 centimetres from peripheral vision) mostly only provides cues for our eye movement (good example of bad error message, based on this, on p. 71). To make an error message visible: (1) put it where users are looking, (2) mark it (often it’s enough placing it next to what it refers to), (3) use an error symbol/icon, and (4) reserve red for errors. Heavy artillery (use with care!): (1) pop-ups, (2) sound (makes users scan the screen for errors; make sure they can hear it!), (3) motion or blinking (but not for more than a quarter- or half-second).
• Visual hints: use pictures where possible to convey function (quicker to recognise; memorable icons hint at their meaning, are distinguishable from others and consistently mean the same even across applications); thumbnails depict full-sized images effectively if they keep features; use visual cues to let users recognise where they are (distinctive visual style, colours, etc).

Expectations

Our perception is biased by our experience, current context and goals. Implications: (1) test your design to make sure different users interpret it in the same way; (2) be consistent with position, colours and font for elements that serve the same function; and (3) understand your users’ goals (they can be different, too!) and make sure you support them by making relevant information clearly visible at every stage.

Memory

We’re much better at recognising than at remembering (“see and choose” is easier than “recall and type”). Tips: (1) avoid modes, or if you can’t, show the current mode clearly; (2) show search terms when showing search results (they’re easy to forget if we get interrupted for whatever reason); (3) when showing instructions for a multi-step process, make sure the instructions are there while following the steps.

Attention and goals

When people focus their attention on their tools, it is pulled away from the details of the task. Software applications should not call attention to themselves. Short-term memory and attention are very limited, so don’t rely on them. Instead indicate what users have done versus what they have not yet done, and/or allow users to mark or move objects to indicate which ones they have worked on versus the rest.

Support people’s goal-execute-evaluate cycle: provide clear paths, including initial steps, for the goal; software concepts should be focused on the task rather than implementation, for the execution; provide feedback and status information to show users their progress towards their goal, and allow users to back out of tasks that didn’t take them toward their goal, for evaluation.

While pursuing a goal, people only notice things that seem related to it, and take familiar paths whenever possible rather than exploring new ones, esp. when working under deadlines. After they’re done, they often forget cleanup steps: design software so that users don’t need to remember, or at least to remind them.

Misc. tips:

• Don’t expect users to deduce information, tell them explicitly what they need to know.
• Don’t make users diagnose system problems. They don’t have the skills.
• Minimise the number and complexity of settings. People are really bad at optimising combinations of settings.
• Let people use perception rather than calculation, when possible (some problems, when presented graphically, allow people to achieve their goals with quick perceptual estimates instead of calculations).
• Make the system familiar (concepts, terminology, graphics), by following industry standards, by making the software work like an older application the user know, or by basing the design on metaphors.
• Let the computer do the math, don’t make people calculate things the computer can calculate for them.

Learning

We learn faster when operation and vocabulary is task-focused, and when risk is low:

• Task-focused operation: you have to understand the users’ goals in order to reduce the gap between what the user wants and the operations supported by the tool is called “the gulf of execution”. To understand goals: perform a task analysis (checklist on p. 135) and design a task-focused conceptual model (the list of objects/actions analysis the user should know about).  The second should be as simple as possible (ie. less concepts), avoid overlapping concepts, and not have things “just in case”. Only then sketch and design a user interface, based strictly on the task analysis.
• Task-focused vocabulary: it should be familiar and consistent (“same name, same thing; different name, different thing”), mapped 1:1 to the concepts.
• Low risk: often people are afraid of being “burned” and don’t learn or explore. People make mistakes, so systems should try to prevent errors where possible, make errors easy to detect by showing users what they have done, and allow users to undo/reverse easily.

Responsive systems

Responsiveness is not the same as performance, it can’t be fixed by having faster machines/software. Principles:

• Let you know immediately your input was received
• Provide some indication of how long operations will take
• Free you to do other things while waiting
• Manage queued events intelligently
• Perform housekeeping and low-priority tasks in the background
• Anticipate your most common requests

When showing progress indicators (always an operation takes longer than a few seconds): show work remaining; total progress, not progress on the current step; start percentages at 1%, not 0% (and display 100% only briefly at the end); show smooth, linear progress, not erratic bursts; use human-scale precision, not computer precision (“about 4 minutes” better than “240 seconds”).

Display important information first. Don’t wait to have all the information to show everything at once.

As a long-time VIM user, I feel it’s my duty to make a micro-introduction to Emacs to VIM users (skip this whole paragraph if you’re not one of them). Emacs is so different than VIM that the comparison doesn’t even make complete sense, but Emacs does have many sweet, sweet features that might tempt VIM users. And let me make this clear: Emacs, in its default configuration, is rubbish. If you don’t like the idea of customising your editor, learning about it, discovering new tricks, “plugins” and shortcuts and maybe even writing your own extensions… use a different editor (eg. I find VIM way better than Emacs on the default configuration). Likewise, if you don’t learn VIM properly and don’t learn the gazillion shortcuts to fly around your code while you stay on the home row… use a different editor. With that out of the way…

A lot of what I’ve learned lately I’ve learned from a handful of websites and Twitter accounts, listed here:

• EmacsWiki: you probably already know this one, but it’s pretty useful for a variety of reasons.
• EmacsRocks / @Emacsrocks: it’s a series of screencasts showing off cool, advanced Emacs features. Each screencast is very short and focused on one thing. Instant awesome.
• EmacsRookie / @EmacsRookie: a blog with articles about different Emacs trips & tricks and features. More geared towards beginners (but my impression is that many people stay “beginners” of Emacs for quite a long time).
• Steve Yegge described “10 Specific Ways to Improve Your Productivity With Emacs“. In particular, I’d recommend making Caps-Lock behave as an extra Control key (I didn’t swap, I just have one more Control key), invoke M-x without the Meta key (both C-x C-m and C-c C-m) and being comfortable with the buffer commands. For navigation, apart from incremental search, you can also use ace-jump.
• Christian Johansen has an interesting intro article to Emacs Lisp.
• Other Twitter accounts worth following are @emacs_knight, @dotemax and @learnemacs.

In particular, things I have learned that I thought would be cool to share:

• The zenburn colour theme. I didn’t really like any of the colour themes that come with Emacs. And although I did see solarized, I thought it looked like crap on Emacs (very different from the screenshots, maybe it only works properly on Emacs 24?).
• hippie-expand is a pretty cool completion system, familiarise yourself with it.
• If you code Perl, you should be using cperl-mode, not the default Perl mode.
• If you code Javascript, you should be using js2-mode, not the default Javascript mode. Also have a look at my js2-mode configuration, you might want to do some of the same tweaks.
• If you have to do anything with XML, make sure you use nxml-mode, including its awesome feature to validate an XML document against a schema.
• yasnippet. Very cool snippet system. Just have a look at the EmacsRocks screencast on yasnippet.
• key-chord. Allows you to assign shortcuts to “key chords” (two keys pressed at the same time). Very comfy esp. if you miss some VIM shortcuts and want certain operations more VIM-like. Also seen on EmacsRocks, and again just check out the EmacsRocks screencast on key-chord.
• And speaking of VIM, have a look at iy-go-to-char, again seen in EmacsRocks (on episode 4). Hint: this works best when combined with key chords.

And last but not least, I have been writing an Emacs major mode for editing AsciiDoc documents (it currently only implements syntax highlighting, which I think is the most important part of a format like AsciiDoc). For that I basically followed the major mode tutorial and then tweaked the multi-line region matching code (for code blocks and such) by setting the font-lock-extend-region-functions variable to a function that appropriately extends the region to be highlighted. If you’re interested, just have a look at my function asciidoc-font-lock-extend-region, essentially copied from some other mode. As a last tip for writing syntax highlighting for major modes, don’t miss re-builder, it’s pure gold for testing your regular expressions!

But enough with the reasons. It’s starting to look like it was a pretty useful mini-project. Not just because I learned a bit more Javascript, the excellent express web development framework and other things, but also because the result itself, even though it didn’t take long to develop (and it was pretty fun, even!), feels useful. It feels like a nice place to put all my notes, TODOs, random ideas for projects, etc. A similar feeling of freedom as when I started using my first Moleskine. Not that I would ditch paper for computer-anything, but it’s useful and freeing in its own way, for specific purposes.

About the technology, I used the Markdown format for the pages thanks to the markdown-js library (it’s really nice that the module has an intermediate tree format that you can parse to add your own stuff before converting to HTML, like e.g. wikipage links!), express for the whole application structure and js-test-driver + jsautotest + a bit of syntax sugar from Sinon.js for the tests (but looking forward to trying out Buster.js when it’s released!). The deployment to Joyent’s Node.js SmartMachine was reasonably easy. Actually, it was pretty easy once I figured the following:

• You must not forget to listen in the correct port, with server.listen(process.env.PORT || 8001)
• There are a couple of pretty useful Node.js-related command-line utilities to check logs, restart applications and so on
• The configuration of the application can be done via npm config, see npm integration on Joyent’s Wiki

If you’re curious to see the code, play with it or use it yourself, take a peek to the Wiki-Toki repository on GitHub. Happy hacking!

I had been thinking of trying out GNOME 3 since it was released. For a number of reasons, I only managed to give it a try a couple of days ago. I normally use KDE 4, but wanted to see how GNOME was doing these days, and wanted to see if it was something I could maybe switch to. I have to say I quite liked some of the stuff I saw, but I don’t think I can switch. My reasons:

• Language switcher keyboard combination: I just couldn’t find any combination I could use. Everything conflicted with some other combination I use (esp. in Emacs). Having to change the keymap by clicking on the top bar didn’t sound sane to me.
• Order of the OK/Cancel buttons: even if I switched, I would probably use a combination of systems. Having to train my brain to look for the buttons in a different position seemed like too much.
• Rhythmbox seemed plain, clunky and hard to use. It seemed hard for me to do what I wanted, plus it crashed consistently while trying to listen to some podcast.
• I kind of like the idea of how workspaces work (even though I have to radically change the way I use them to adapt to them), but for me it’s too much that both (a) closing the last window makes the workspace disappear and (b) you can’t create workspaces “above”. That is a deal-breaker for me.
• Can’t create workspaces on the right or left? I could get used to that probably, but it added up to my frustrations with GNOME 3 workspaces.
• Constant repainting issues.
• Can’t make sense of the window traversing. Let’s say I have two virtual desktops, one with a browser and another one with two terminals. The focus is on one of the terminals, and I want to go to the other terminal (with the keyboard, of course). If I just press Ctrl-Tab GNOME takes me to the web browser in the other desktop! If I want to go to the other terminal, I have to press Ctrl-Tab, Shift-Ctrl-Tab to go back to the terminal, arrow down to see all the terminal windows, arrow right to go to the next terminal. It’s even worse when I have Opera in one virtual desktop (maximised) with the error console in the same desktop. As Opera is maximised, I can’t even click with the mouse, so the only way to switch to the error console I can think of is doing the dance described above. Am I missing something, is this for real? EDIT: I was told about Ctrl-` (changes between windows of the same application). Cute attempt, but I don’t think I can get used to thinking if I have to use Ctrl-TAB or Ctrl-`. So that remains “impossible to use” for me.

I wonder if some GNOME user can shed light on some of those issues, although it doesn’t seem like I can find a solution for all my frustrations :-)

Structure

The book teaches how to write web applications using Javascript, always following the MVC pattern. It’s divided in four parts:

1. The first two chapters serve as an introduction to both the MVC pattern and the Javascript language. Although this book is not aimed at total Javascript newbies, you don’t have to know that much to follow the book. For example, it explains prototypes and constructor functions.
2. Chapters 3 to 5 cover the implementation details of MVC in Javascript (one chapter for the Model, another for the Controller and the last one about the View).
3. Chapters 6 to 10 cover many practicalities of client-side web development, like dependency management, unit testing, debugging, interesting browser APIs and deployment tips.
4. The last three chapters cover Javascript libraries: Spine, Backbone and JavascriptMVC.

Additionally, there are three appendices covering jQuery, Less and CSS3.

Highlights and references

• Chapter 10 (“Deploying”) is full of very good tips and information.
• Both the Backbone and the JavascriptMVC chapters were brilliant, looking forward to use any of them soon.
• All the example code is on GitHub.
• Page 24: “The secret to making large Javascript applications is not make large Javascript applications”.
• HJS plugin for jQuery for a nice syntax to create classes.
• ES5-shim for browsers that don’t support Ecmascript 5 yet.
• Chapter 2 was a very good introduction about events. removeEventListener (p. 41), stopPropagation/preventDefault (p. 43), list of properties (p. 44), load vs. DOMContentLoaded (p. 45), delegating events (p. 46) and custom events (p. 47-49), among others.
• Reference to blog post about namespacing.
• Object.create discussed on page 55.
• Using URL hash for URLs on pages 82, 83.
• Didn’t really understand the explanation for the HTML5 history API on p. 85. Alternatively, see the HTML5 history API on Dev Opera.
• Very interesting file API on p. 103 and p. 111. Forget the drag-n-drop (reason) and the copy/paste.
• Tips about when to load your Javascript on p. 156.
• The JavascriptMVC chapter was brilliant, see p. 208-213 for the class syntax (nicer and more compact, supports this._super()), p. 210 for instrospection and namespaces, p. 211, 212 for model attributes and observables, and p. 213 for setters. Very cool server encapsulation on p. 215. Type conversion and CRUD events on p. 218. JMVC views on p. 219. Templated actions and final example on p. 226-228.

Note that all page references are pages in the PDF file, not pages in the book!

Wrapping up

This book is packed with very practical information and a lot of code that will teach you how to write applications in Javascript. It builds up from relatively simple code to more advanced stuff, including tips, use of libraries, etc. It’s one of those books that makes you want to play with all the stuff you’re learning, and try it all in your next project.

However, sometimes the amount of code makes the book hard to read. Some parts (eg. beginning of the chapter about controllers) are a bit tiring as you have to read and understand so much code, esp. if you’re not that used to reading more-or-less advanced Javascript. It also lacks information about some important tools like Dragonfly (it almost feels like there’s nothing for developing with Opera) or js-test-driver.

In summary, this is the perfect book if you know a bit of Javascript and want to learn modern techniques and libraries that will get you started in serious client-side programming. Especially if you are one of those server-side programmers that don’t like Javascript but has to use it anyway (because despite all its warts, it’s a really nice language!). If you’re a Javascript wizard and you have been developing client-side code for years, this book may not be for you.

What I decided to build is a very simple interface to search for leaked cables. I called it LeakyLeaks (see the code on GitHub). Unfortunately the LeakFeed API is quite limited, so I had to limit my original idea. However, I think the result is kind of neat, especially considering the little effort. To build it, I started writing support classes and functions using Test-Driven Development with Jasmine. Once I had that basic functionality up and running I started building the interface with Bootstrap and, at that point, integrating the data from LeakFeed with Angular was so easy it’s almost ridiculous. And as LeakFeed can return the data using JSONP, I didn’t even need a server: all my application is simply a static HTML file with some Javascript code.

All this get-data-from-somewhere-and-display-it is astonishingly simple in Angular. There’s this functionality (“resources“) to declare sources of external data: you define the URLs and methods to get the data from those resources, and then simply call some methods to fetch the data. E.g.: you can get the list of all tags in LeakFeed from http://api.leakfeed.com/v1/cables/tags.json (adding a GET parameter callback with a function name if you want JSONP). Similarly, you can get the list of all offices in LeakFeed from http://api.leakfeed.com/v1/cables/offices.json. In Angular, you can declare a resource to get all this information like this:

this.LeakFeedResourceProxy = $resource(
 'http://api.leakfeed.com/v1/cables/:id.json',
 { callback: 'JSON_CALLBACK' },
 { getTags:    {method: 'JSON', isArray: true, params: {id: 'tags'}},
   getOffices: {method: 'JSON', isArray: true, params: {id: 'offices'}}}
);

Once you have declared it, using it is as simple as calling the appropriate method on the object. That is, you can get the tags by calling this.LeakFeedResourceProxy.getTags(), and the offices by calling this.LeakFeedResourceProxy.getOffices(). And when I say “get the tags”, I mean get a list of Javascript objects: no JSON, text or processing involved. If you assign the result of those functions to any property (say, this.availableOffices), you’ll be able to show that information like so (the |officename is a custom filter to show the office names with a special format):

<select id="office" name="office"> \
  <option value="{{o.name}}">{{o.display_name|officename}} ({{o.cables}})</option> \
</select>

The cool thing is, thanks to Angular’s data binding, anytime the value of that variable changes, the representation in the HTML changes, too. That is, if you assign another value to this.availableOffices the select box will be automatically updated to have the new set of options! But the data binding is two-way, so any changes you make in the UI also get reflected back in the Javascript variables. This further simplifies many tasks and makes programming with Angular a breeze.
There are other nice things about Angular (and many nice things about Bootstrap and Jasmine of course!), but I think that’s enough for today :-)

Principles

Most prototyping mistakes come from either (1) building too much or too little, (2) prototyping the wrong thing or (3) not setting expectations about what the prototype will be. Principles:

1. Understand your audience and intent. This is the most important principle. Once you understand them, you’ll be much better equipped to determine what you need to prototype, set appropriate expectations, determine the right level of fidelity and pick the right tool.
2. Plan a little, prototype the rest. Software systems change constantly and quickly. Plan a little and prototype the rest, so you can cope with the changing environment by working incrementally and iteratively.
3. Set expectations. This lets you avoid rabbit-hole discussions on things that aren’t important or haven’t been prototyped yet.
4. You can sketch. Anyone can draw well enough for the purposes of a prototype.
5. It’s a prototype, not the Mona Lisa. Don’t lose too much time on making it pretty. Not only it’s not necessary, but it has some advantages like making it clear that it’s not finished product, which makes people more likely to give feedback. You need the least amount of effort to communicate your design idea, nothing more.
6. If you can’t make it, fake it. You can fake many things you can’t make with JPG files, clickable HTML files, PDFs or PowerPoint presentations.
7. Prototype only what you need. Often prototypes only cover part of a system. Even if your ultimate goal is usability testing, chances are you’ll only test 5 or 6 scenarios, so you only need to build that.
8. Reduce risk—prototype early and often. Prototyping is about making small investments with a significant return. The return can be positive, in which case you can just go ahead, or negative, in which case your risk is substantially reduced because you identified the problem soon enough. The earlier you catch mistakes, the easier and cheaper it is to fix them.

Tools

When choosing the prototyping tool, consider audience, intent, familiarity/learnability, cost, need for collaboration, distribution and throwaway vs. reusable. Notes for specific tools follow:

Paper

It’s the most versatile method. It’s also fast, cheap, easy, you can manipulate it on the fly (and even the participants can help), collaborative, not limited by prebuilt widgets or technology, and can be done anywhere and anytime, even without computers. The bad sides are that it’s hard for geographically distributed teams to use it, requires imagination and lacks visual aesthetics. Tips:

• Include transparencies (useful for simulating roll-overs and such), post-it notes (for displaying changing states on the page, highlighting elements or dialog windows), coloured pens/markers (sketching in black/blue, errors in red, success messages in green) and scotch tape or glue stick in your kit.
• Use pre-drawn/printed widgets. The book resources include a (kind of limited) sample Illustrator file with printable widgets for that purpose.
• You can use transparencies for context, pop-up help (even using a marker to highlight fields).
• To accomplish a show/hide effect, you can fold/unfold part of the paper.
• You can simulate slide effects by having two different pieces of paper, cut one of them so the other fits (leaving a sort of “window” so you can see the other through), and moving the second one back and forth.

Presentation software

It has a low learning curve, it’s available in most computers, you can use master slides to ensure consistency, you can copy-paste and rearrange elements with drag-and-drop, and export to HTML or PDF if necessary. However, it has limited drawing tools (so often not good for hi-fi prototypes), the interactivity is limited and the prototype has no reusable source code whatsoever. The book resources have a sample prototyping kit for Powerpoint and Keynote, and Manuela Hutter (Oslo UX book club organiser) wrote another prototyping kit for OpenOffice.org (and see the whole blog post about prototyping with OO.o). Tip: you can simulate fade effects in presentation software by having two slides (one with the element highlighted, the other without) and setting a “dissolve” transition effects between them.

HTML

There are several ways to approach making prototypes with HTML. You can simply slap up a few images and use image maps to link to each other, you can have HTML exported from some other tool, or you can write “production-level” HTML for a prototype that will contain potentially reusable code. The strengths of the last way are being platform-independent, free, portable, “real” (in case we’re prototyping a web app), it helps gauging feasibility, modular (helps in productivity), collaborative (if we split in different files), reusable code and unlimited potential. The downsides are that it might take more time and effort to make a prototype like this, and that it’s not easy to make annotations on it.

Testing your prototype

Common mistakes

1. Usability testing is a process, not an event. There’s also planning, analysis and reporting, not just “sitting in front of a person with a computer”.
2. Poor planning. The first question to ask is “why am I doing usability testing?”. Determine who you want to test, who is going to use the product or service, what are their behaviours, and why would they use the product in the first place.
3. Not recruiting the right participants. The whole point of the testing is seeing how the design works in the eyes of the people who will use it. If you recruit the wrong people, you will get the wrong data.
4. Poorly-formed research questions. This is one of the biggest challenges. You have to get your answers without asking explicitly. Instead of telling them to plan a dinner + movie, you can ask them to look for something to do with friends. The point being we shouldn’t make them use the application in the way we want, but make them use the application in whatever way they normally would.
5. Poor test moderation. A good moderator balances being a silent fly on the wall, watching, with asking enough questions to get the test going; know how to extract just the right level of detail; know when to let the participant explore, and when to pull them back; how to get the answer to the question they want without asking it.
6. Picking the wrong method to communicate findings and recommendations. Nobody is going to read a 10-20 page report. Short presentations with a summary of the findings typically work well. Including video clips showing the highlights of the test is useful.

Steps to conduct a usability test

1. Preparation. Decide, with your team, what are the key characteristics and behaviour you’re looking for, and also the ones you don’t want. If you’re going to record audio or video, have a waiver ready for the participants. Knowing the intent of the test will inform the appropriate scenarios, research questions and prototype. Limit the test to 45-60 minutes: enough time to test 5 or 6 scenarios while not exceeding the attention span of the participants.
2. Design test scenarios. Either specific to determine if a user can access a concrete feature of the site, or exploratory to gain insight into a participant’s overall approach to solving her goal. Focus on the goal, allowing different activities and process to reach it.
3. Test the prototype. Getting feedback from participants is easier if they feel comfortable. Once they’re comfortable, ask them about their experiences related to whatever you’re going to test that day. You can use that information to provide context.
4. Record observations and feedback. Have one person moderating, and another person taking notes remotely. It’s better to over-record than to under-record. Use a rating scale of, say, 1-5 for each scenario. Both moderator and participant fill it in. The former should be based of measurable elements like time and effort. The latter is more subjective, focused on the satisfaction with completing the task. Try to filter any variable not related to the system you’re testing. For example, use the same operating system as the user is most used to.
5. Analyse and determine next steps. When you finish, you typically have a list of bigger issues in your head. This list is a starting point. Analyse all your data points, and find themes. Look for frequency, severity and learnability. It’s better to use a method that combines significance to the customer, value to the business and technical feasibility of fixing the issue.

And that’s the end of my summary.