Coding Horror

There's an interesting comment in this Amazon user review of The Microsoft Manual of Style for Technical Publications:

My favorite entry, especially fun to find in light of Microsoft's legal problems arising in part from its relationship to Netscape Navigator, is this Orwellian directive, found on p. 185: "Navigate. Avoid the verb 'navigate' to refer to moving from site to site, page to page within a site, or link to link on the Internet. [...] Instead, use 'explore' to mean looking for sites or pages generally..."

Would you rather be a Navigator or an Explorer? And what, exactly, is the implied meaning of this IE error:

The wording of the "Navigation Canceled" error message can't possibly have been a coincidence, given the intense rivalry with Netscape Navigator back in the heady days of Internet Explorer 3 and 4. The message now seems quaint in the wake of Netscape's near-irrelevance. Still, I wonder which cheeky little monkey at Microsoft came up with this particular error message way back when.

Of course, there's a long history of semi-friendly rivalry between Internet Explorer and its browser competition. In 1997, immediately after the release of Internet Explorer 4, Microsoft dropped a giant IE logo on the Netscape campus.

And more recently, the Internet Explorer team sent the Firefox team a cake to congratulate them on the release of Firefox 2.0.

Nicholas Zakas enumerates the number one reason why good JavaScript libraries fail:

Lack of documentation. No matter how wonderful your library is and how intelligent its design, if you're the only one who understands it, it doesn't do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.

James Bennett expresses a similar sentiment in choosing a JavaScript library:

There's one other thing which can really make or break a JavaScript library, and it's surprising how often it's overlooked, because the same thing makes or breaks an awful lot of software in other fields: documentation. The greatest library in the world would fail if the only way to learn it was reading the code (and, in fact, it already has to a large extent). Some packages have managed to overcome this by way of lots of unofficial documentation -- blog entries and the like -- but there is absolutely no substitute for full, well-written documentation. The ideal, for me, consists of:

1. High-level overviews of each part of the library, touching on key objects and methods.
2. Practical examples showing how to handle common use cases.
3. Full API documentation for everything in the library. JSDoc is both good and bad for this: good because it makes API docs stupidly easy to generate, and bad because people assume that API docs are all you need. Javadoc, which inspired JSDoc, has wrought much ill on the Java world for largely the same reasons.
4. Comments throughout the code itself.

Pretty much everybody who's developing a JavaScript library has dropped the ball on this; very few libraries manage even one or two of those points, and out of the teeming multitude of JavaScript libraries floating around today I've seen exactly one which manages to hit all four points with any kind of success. Maybe there are other splendidly-documented libraries out there, but I've yet to see them; most treat documentation like an afterthought.

Mike Pope, who writes documentation for a living, neatly summarizes both opinions with this zinger:

We've been known to tell a developer "If it isn't documented, it doesn't exist." Not only does it have to be doc'd, but it was to be explained and taught and demonstrated. Do that, and people will be excited -- not about your documentation, but about your product.

Good documentation is hard to find. Particularly on open source projects. That's why I was so pleasantly surprised to see such excellent documentation for the open-source UrlRewriting.net project, along with a support forum.

The UrlRewriting documentation (pdf) is a pleasure to read. Far from being an afterthought, documentation was a first-class citizen on this project, and it shows. The presence of good documentation makes the code a pleasure to use, too.

So how do you keep your documentation up to snuff on a rapidly moving project? Maybe it's possible to use agile documentation methods alongside agile coding practices. Mike Pope's recent post on the "agile little" ASP.NET AJAX documentation set is a hopeful sign that we, too, can generate better documentation, faster.

Part of Chuck Jazdzewski's fatherly advice to new programmers is this nugget:

Programming is fun. It is the joy of discovery. It is the joy of creation. It is the joy of accomplishment. It is the joy of learning. It is fun to see your handiwork displaying on the screen. It is fun to have your co-workers marvel at your code. It is fun to have people use your work. It is fun have your product lauded in public, used by neighbors, and discussed in the press. Programming should be fun and if it isn't, figure out what is making it not fun and fix it. However, shipping isn't fun. I often have said that shipping a product feels good, like when someone stops hitting you. Your job is completing the product, fixing the bugs, and shipping. If bugs need fixing, fix them. If documentation needs writing, write it. If code needs testing, test it. All of this is part of shipping. You don't get paid to program, you get paid to ship. Be good at your job.

It's true. One key measure of success for any programmer is how much code you've shipped. But merely shipping is not enough. A more meaningful measure of success is to ask yourself how much code you've shipped to living, breathing, real-world users. But then total users doesn't equal total usage, either.

How many users actually use your application? Now that's the ultimate metric of success.

But it's a little scary when you start doing the math. Rich Skrenta explains:

I was just an engineer in this group, but the reality of what was happening in the market to our product line started to seep in. Here I was putting all of this effort into stuff that never would be used by anyone. It was still intellectually challenging...like doing crossword puzzles or something. But it had no utility to the world.

I started to look around and I saw many other examples of groups working on stuff that no one would ever use or care about. Mobile IP initiatives, endless work around standards that nobody cared about, research from the labs that would never be applied or even cited.

Yikes.

I had written stuff that people actually used, before. It felt good. I had written a usenet newsreader that was used by hundreds of thousands of people. I was running an online game, as a commercial hobby on the side, which had several hundred paying customers. Sheesh, I thought. My side projects have more customers than my day job.

So I made a simple resolution. I wanted to work on stuff that people would actually use.

This sounds simple. But if you walk the halls of Sun, AOL, HP, IBM, AOL, Cisco, Siebel, Oracle, any university, many startups, and even Google and Yahoo, you'll find people working on stuff that isn't going to ship. Or that if it does ship, it won't be noticed, or won't move the needle. That's tragic. It's like writing a blog that nobody reads. People make fun of bloggers who are writing "only for their mother". But what about the legion of programmers writing code paths that will never be traversed?

It's for precisely this reason that I've often wondered if writing code is really the most effective way for software developers to spend their time. A software developer that doesn't write code-- sacrilege, right?

But wait a minute. A smart software developer knows that there's no point in writing code if it's code that nobody will see, code that nobody will use, code that nobody will ultimately benefit from. Why build a permanently vacant house?

A smart software developer realizes that their job is far more than writing code and shipping it; their job is to build software that people will actually want to use. That encompasses coding, sure, but it also includes a whole host of holistic, non-coding activities that are critical to the overall success of the software. Things like documentation, interaction design, cultivating user community, all the way up to the product vision itself. If you get that stuff wrong, it won't matter what kind of code you've written.

If, like Rich Skrenta, you want to work on software that people want to use, realize that it's part of your job to make that software worth using.

Don Park invented Identicons last week.

An Identicon is a small, anonymized visual glyph that represents your IP address. Don explains it better than I do:

I originally came up with this idea to be used as an easy means of visually distinguishing multiple units of information, anything that can be reduced to bits. It's not just IPs but also people, places, and things.

IMHO, too much of the web what we read are textual or numeric information which are not easy to distinguish at a glance when they are jumbled up together. So I think adding visual identifiers will make the user experience much more enjoyable.

I think identicons have many use cases. One use is embedding them in wiki pages to identify authors. Another is using them in CRM to identify customers. I can go on and on. It's not just about IP addresses but information that tends to move in 'herds'.

It's genius. And the simple algorithm Don came up with produces beautiful, unique results. Just scroll through the comments on his blog to see Identicons in action. They work amazingly well, even at 16x16. Jon Galloway and I were inspired. We rolled up our sleeves and ported Don's Identicon code from Java to .NET 2.0.

Download the Identicon 1.3 sample for .NET 2.0 (13 kb)

Identicons aren't just for show. They're quite practical. Rather than printing everyone's IP address next to their comment, you can show their anonymized Identicon. It's more private, it's almost as useful, and it's much more fun. Download the sample and try it yourself.

(updated 3/18/2007 V1.3: fix a few minor bugs, improve documentation)

While reading Larry O'Brien's latest column in SD Times, I couldn't help noticing that the article text was dwarfed by the advertisements.

I was curious exactly how much of the page was dedicated to advertising. There's a clever technique used in the book Homepage Usability: 50 Websites Deconstructed to measure the composition of webpages.

The fifty corporate homepages used in the book didn't contain much advertising, but I was still amazed how little screen real estate is dedicated to actual content. Let's apply the same technique to the SD Times page. I'll highlight navigation, content, and advertising.

A full third of the page is dedicated to advertising. That's more than the content itself!

I carried a torch for micropayments for years, but it's never going to happen. Ad-supported content appears to be the only sustainible business model on the internet. Clay Shirky has been saying this for years. Just open a web browser and it's painfully obvious that he was right. The web is awash in advertising.

This model, which generates income by making content widely available over open networks without charging user fees, is usually called 'ad-supported content', and it is currently very much in disfavor on the Internet. I believe however, that not only can ad-supported content work on the Internet, I believe it can't not work. Its success is guaranteed by the net's very makeup - the net is simply too good at gathering communities of interest, too good at freely distributing content, and too lousy at keeping anything locked inside subscription networks, for it to fail. Like TV, the net is better at getting people to pay attention than anything else.

Indeed, ad-supported content is the house that AdWords built. It's difficult to criticize a system that works, a system that allows content creators to at least break even on their hosting costs.

We watched the movie Idiocracy this weekend. It's a brilliant bit of social satire from Mike Judge, which (among other things) takes ad-subsidized content to its logical extremes. People wear nothing but clothes plastered with corporate logos. Wallpaper and lampshades are made up of patterns of tiny corporate logos. Every square inch of every imaginable surface is covered with billboards and even more advertisements.

Watching television in Idiocracy bears an unfortunate resemblance to reading that SD Times article. To be fair, Larry's content is a bit more highbrow than "Ow! My Balls!". But it's still a tiny window of content, surrounded by dozens of flashing, animated advertisements. It's a disturbing vision of the future. It's supposed to be funny, but it's uncomfortably close to the experience of reading today's ad-supported internet content. Are we creating a world of endless advertising?