Documentation Needs Examples (Duh)

I’m constantly amazed at the amount of documentation people are inclined to create without including a single example.

Man pages that devote pages worth of command-line options, flags, grammar, caveats, historical anecdotes, and NOT A SINGLE EXAMPLE.

Textbooks that devote pages to a particular API, then expose it all in one monolithic program.

Countless reference documentation on HTML tags and CSS grammar, and NOT A SINGLE EXAMPLE.

In a world where free videos make it stupidly obvious how to kickstart your lawmowing experience and watching a screencast precedes the creation of “Hello World” in any language you care to adopt, let’s get it straight: An example says a thousand words.

Where’s that Sound Coming From?

Stop the Noise. Don't really stop the noise, I usually like it, but nonetheless I like this photo too.

Sound Thinking

Where's that sound coming from?
An app inside my box?
Is it ITunes on the desktop
Or YouTube in the 'Fox?

A Skyper shouting at me?
Or Pandora playing faves?
Media Player come to life?
Hmmm ... Real with recent saves?

A podcast I'm preparing?
A vidcast made for nerds?
Nope, it seems to be this picture,
It says a thousand words!

Huh?

I started writing the first four lines of this post when I realised I was writing a “poem”, so I just kept going even though I’m clearly no “poet”.

Anyway, my point is:

  • People multitask, running ten or more browser and desktop apps at the same time.
  • Sound is arising a lot inside the browser these days, and I’m not talking about Axel F midis running in an off-colour GeoCities page. YouTube and wannabees, Flash telephony like JaJah, Podcasts being played by publishers as well as aggregators, Flash and Ajax games. Hopefully we’ll see more Ajax developers introduce Richer Plugins to include sound, because good sound effects make interaction more productive and more fun.
  • So I’d like to see an app that locates the visual source of the sound, which 95% of the time, can indeed be traced back to a particular window or browser tab. And if there is such an app, it should be baked into the OS. For instance, you could use an Alt-Tab-like sequence to isolate each sound as you rotate through the various sources. Nothing more annoying than having twenty browser tabs open and not knowing where the sound is coming from.

Update Feb 26, 2012: And finally Chrome introduces it. Available now on Canary channel.

Who Needs These Browser Warnings?

Setting up a new Windows PC today and not loving the browser warnings.

The messages, as I recall them: “You are about to submit the form. It’s dangerous.”, “You’re going to leave the page. It’s dangerous.”, “This page is encrypted. It’s dangerous.”, “This page is not encrypted. It’s dangerous.”, “This is H20. It’s dangerous.”

So my question is, who’s benefitting? At this stage, the majority of internet users have been submitting forms and using encrypted pages for 5+ years. And if they’re a newbie, is it any more useful to them? (Hint: No.)

The only thing it does is add overhead to setting up a new system. You have to stop and think, “Hmmm is this a negative, double-negative, or triple-negative question? Ah, okay, I think I’ll leave the checkbox unchecked so as to imply I don’t want to not submit the form. And also, I’ll leave the ‘Don’t show me again box’ so it doesn’t not show me again.”

Summary:

  • Only provide dialog boxes that are useful, otherwise users will ignore them all.
  • Avoid not excluding negative phrasing in your options. Even if the most likely value is negative, you should still phrase it as a positive. (“Remember this” as opposed to “Forget this” or “Don’t remember this.”)

More is Sometimes Less

Someone sent Don Norman a critique implying that a machine was more usable because it contained only one button. His response is interesting:

Nice story, but wrong. Fewer buttons do not necessarily mean easier use … When assessing simplicity, don’t get all hung up on the number of buttons. Look at the whole picture: more is sometimes less.

The sentiment will resonate with anyone who’s tried to set an el cheapo digital clock, the kind of clock that skimps on an hour button and makes you run through all 1440 minutes of the day. Slow. Or tried to set the time on a digital watch, whereupon you learn in the manual (if you’re fortunate enough to have kept it) that you must depress down “Button B” for 3 seconds. Confusing.

The same thing happens with language. Sometimes introducing a new term for something reduces complexity overall. When talking about software architecture, for example, life would be a lot more tedious if you didn’t have terms like “Factory”, “Singleton”, “Proxy”.

Mix ’06 and Ajax Design Principles

‘Tis Goud reports from Mix ’06, Microsoft’s web bash currently happening in Vegas. One of the presentations focused on the most important thing about Ajax: Usability.

The session started with referencing two sites with information on:

Thomas’s guidelines were the first serious look at Ajax usability and a big inspiration for the Ajax Patterns.

The patterns and the principles were apparently distilled to this list:

  • Feedback
  • Predict
  • Preserve
  • Share
  • Controls
  • Separate

If anyone has more detailed info on this discussion, please let me know!

As it happens, the third chapter of “Ajax Design Patterns”, the overview to the patterns themselves, explicitly identifies principles on which the patterns were based. Principles and patterns go hand-in-hand, so any pattern language I’ve worked on always comes with a set of principles, an explicit reference point for people to grasp where the patterns are coming from. You can even (with some energetic hand-waving) look at the patterns as being defined around the principles: “These patterns are written such that if you follow them, your system will adhere to these principles”.

Anyways, the principles are broken into two groups: Usability Principles and Software Design Principles. Maybe I ought to podcast them sometime.

These are the Usability Principles for Ajax.

  • Follow Web Standards
  • The Browser is Not a Desktop
  • If it’s Different, Make it Really Different
  • Provide Affordances
  • Smooth, Continuous, Interaction
  • Customisation
  • Make it Fun

These are the Software Design Principles for Ajax.

  • Embrace Javascript
  • Accept Workarounds Where Necessary
  • Tame Asynchrony
  • Develop for Compatibility
  • Reduce Bandwidth
  • Deal with Latency
  • Partition into Multiple Tiers
  • Go Easy on the Browser
  • Practice Graceful Degradation

It’s funny. The very first thing I think of when I see stuff like this is along the lines “SHOW ME THE PATTERNS!!!!”. I’ve got no patience for motherhood statements like ‘Tame Asynchrony’. But the reason for this annoyance is because you usually see these kind of principles in the absence of any explanations, examples, or patterns. Once it’s apparent that the principles are merely a background to more concrete advice, their presence has been justified.

Wikipedia as a Honeypot

How long until wikipedia becomes a honeypot?

“Who wants to be a millionaire” contestant is struggling to answer the question, “What year did the Fonz jump the shark?”, and calls out to Lifeline Buddy. Back in 2005, Lifeline Buddy would have googled for the answer. But this is 2007, and “wiki” is now a household name (the media refers to “wiki” and “wikipedia” interchangeably). Lifeline Buddy bangs out “fonz jump shark” into wikipedia’s search field and quickly finds the right page, reporting confidently the year was 1975. Only, it’s wrong; Fonzarelli, of course, jumped the shark in 1977. The producers had entered the fraudulent details at precisely the moment the lifeline was consulted. Contestant takes his $1000 consellation and exits, muttering something about the Britannica under his breath.

Producers wouldn’t stoop so low? If the BBC can do it, draw your own conclusion. The Register, in any event, would have a field day with their latest whipping boy.

Instead of restorting to restricting edits, wikipedia first needs to try out a “heat map” view to help people decide how stable the information is. Not as gaudy as the Ajax Patterns authoring heatmap (using a more subtle theme now), but some way for people to know what’s new and what’s old. Again, this comes back to the idea of separating out wiki content from presentation, ideally using some kind of web service. A wiki needs more than one view, even without any Maps/Flickr/Delicious mashup. For example, you could have three standard views:

  • Pure wiki reading, just like wikipedia today.
  • Stability view. e.g. Most content in white as now, but with a few shades of grey to distinguish how old each phrase is (darker grey = past minute, medium grey = past hour, light grey = past day; so a phrase “graduates” from grey to white as it matures).
  • Inspection mode. Full-on data mining interface, using Ajax (of course) to explore history, drill down to author info, etc.

Wikipedia as a Honeypot

How long until wikipedia becomes a honeypot?

“Who wants to be a millionaire” contestant is struggling to answer the question, “What year did the Fonz jump the shark?”, and calls out to Lifeline Buddy. Back in 2005, Lifeline Buddy would have googled for the answer. But this is 2007, and “wiki” is now a household name (the media refers to “wiki” and “wikipedia” interchangeably). Lifeline Buddy bangs out “fonz jump shark” into wikipedia’s search field and quickly finds the right page, reporting confidently the year was 1975. Only, it’s wrong; Fonzarelli, of course, jumped the shark in 1977. The producers had entered the fraudulent details at precisely the moment the lifeline was consulted. Contestant takes his $1000 consellation and exits, muttering something about the Britannica under his breath.

Producers wouldn’t stoop so low? If the BBC can do it, draw your own conclusion. The Register, in any event, would have a field day with their latest whipping boy.

Instead of restorting to restricting edits, wikipedia first needs to try out a “heat map” view to help people decide how stable the information is. Not as gaudy as the Ajax Patterns authoring heatmap (using a more subtle theme now), but some way for people to know what’s new and what’s old. Again, this comes back to the idea of separating out wiki content from presentation, ideally using some kind of web service. A wiki needs more than one view, even without any Maps/Flickr/Delicious mashup. For example, you could have three standard views:

  • Pure wiki reading, just like wikipedia today.
  • Stability view. e.g. Most content in white as now, but with a few shades of grey to distinguish how old each phrase is (darker grey = past minute, medium grey = past hour, light grey = past day; so a phrase “graduates” from grey to white as it matures).
  • Inspection mode. Full-on data mining interface, using Ajax (of course) to explore history, drill down to author info, etc.

Redundant Design is Worth Fighting For

Matt @ 37Signals discusses new countdowns being used at pedestrian crossings (crosswalks). Did you ever count how many redundant messages are available at a pedestrian crossing? Good, let’s be sad together and count them, then. At a workshop one time, various attendees from different countries came up with a list of cues, something like the six below:

  • The walking man (is there a walking woman anywhere in the world?) or “Walk”/”Don’t Walk” message.
  • The main traffic lights for drivers.
  • Countdown displays.
  • Display next to the button, indicating if it’s already been pushed (in which case, currently in “Don’t Walk” mode).
  • Sound. (A continuous noise to indicate whichever phase they’re in, and/or a transition sound.)
  • Cars and pedestrians. (Not actually designed and not reliable, but certainly an indication.)

The redundancy is presumably to cope with different sets of disabilities, as well as improve safety for everyone. Software developers don’t always like redundancy – it goes against just about every fundamental design principle you care to name – but users generally benefit from it. So it’s a matter of architecting things so that redundant UI doesn’t lead to redundant code. e.g. point two event handlers to the same Command object.

Yeah, another funny thing about crossings is the button. In one place (Singapore?), I was told not to push it, because it’s only for disabled or elderly people (and of course, ignorant tourists). Everyone else just waits and it will turn green eventually.

Error Messages We’d Rather Not See

Uh, thanks for the heads-up.

Reminds me of a presentation at Interact 2001, where the laptop suddenly interrupted proceedings with that legendary message, “Your computer is now fully charged”. The presentation was about user attention, I kid you not.

And, by way of contrast, how to write good error messages: tell the user what happened, explain the consequences if it’s not obvious, outline how to fix it, explain what to do if they can’t fix it.

Error Messages We’d Rather Not See

Uh, thanks for the heads-up.

Reminds me of a presentation at Interact 2001, where the laptop suddenly interrupted proceedings with that legendary message, “Your computer is now fully charged”. The presentation was about user attention, I kid you not.

And, by way of contrast, how to write good error messages: tell the user what happened, explain the consequences if it’s not obvious, outline how to fix it, explain what to do if they can’t fix it.