Macintitis

I'm starting with Macintitis because I first learned this general lesson in 1994, but apparently not well enough. Apple has succeeded in getting most of the CodeZoo team to switch to Mac, and as a result we spent much of our time reviewing the site during development through Mac browsers and Mac monitors. Of course, that's stupid -- most visitors to CodeZoo have not yet made the switch. As we got towards launch, we found that the site is terribly broken in older versions of Mozilla/Firefox on Linux, which is a more important platform for O'Reilly than for many other sites. Dumb, dumb, dumb.

You can't assign developers a primary work platform just to ensure diversity, and expect them to be happy. As Jason pointed out in my interview with him on ORN, developers will be happier using whatever programming language with which they're most comfortable, and of course the same applies for text editors, web browsers, and operating systems. You do have to make sure, though, that someone is looking at the site through all of the platforms you care to support, very frequently. Don't leave browser and platform testing to the end. Each new design, template, or page should get a once-over in any browser a user is likely to use -- and probably a bunch they're unlikely to use, too.

My friend Nelson told me he planned to look at the site in Lynx as a way of testing it, and what do you know, it broke in Lynx. Does that matter for anyone other than Nelson? Well, Lynx is a good lowest common denominator, and if it works in Lynx, it probably works on cell phones, airport web terminals, WebTV sets, old versions of Netscape, and whatever other freaky browser a user might choose to use. You know what? All of the browsers I just mentioned already show up in CodeZoo's access logs. So yes, Lynx is a great test. Use it.

Examples

I really like the 37signals "blank slate" model for just-opened interfaces, and I wanted to do something similar. CodeZoo allows users to submit Amazon-style ratings of components, and also to contribute tips for how best to use components. We used the 37s "EXAMPLE" model to show what reviews and tips will look like on a page if none have yet been submitted.

While Jason and I were chatting before launch, he asked if the model was really useful in this context; there already is plenty of component descriptive content on our pages before the user gets to it, so why do we need examples? We wound up agreeing that the good thing about this use is that the user gets good review style modeled for them -- they can see appropriate length, tone, and detail in the example, and use that in their own contributions.

Unfortunately (Macintitis again), we didn't test the visibility of the red "EXAMPLE" text on different monitors, and some users couldn't see the red text on their setup. They thought the Star Wars-themed example reviews were bugs in the system. "Why is R2-D2 reviewing Hibernate?" Again, assume that every wristwatch-with-a-browser will hit your site at some point, and plan accordingly.

Playing dead

We used Joel Spolsky's "playing dead" model for inappropriate user submissions -- a user who submits a tip or review will always see it on the site immediately, but other users won't see it unless and until it is approved by the moderators. If the submission is abusive or inappropriate, the submitter will think they've succeeded in spamming or subverting the site, but no one else has to worry about that. Suffice it to say this has already been a huge help. You have to assume people will try to use any community software to spam or otherwise misuse the system; playing dead is a great way to minimize the harm of that misuse.

Reduce, reduce, reduce

The greatest interface work we did on CodeZoo came from reducing the number of choices a user had to make to get a component. The worst parts of CodeZoo, in my view, are where we didn't reduce enough. Reduce, reduce, reduce, and then reduce some more!

Many other open source code repositories will revel in options for a user: what packaging format do you want? which version? what platform? which variation? We started with a simple goal: for any component, there should be one button that allows any user to get that component. We called this the "buy button." Where there were multiple versions available, we chose the most recent, stable version and made that the default. Where there were multiple packages, we chose the Zip format (which is widely available on any platform) and got rid or tar.gz, tar.bz, .exe, and everything else we could. If there were many parts of the component, we defaulted to the one file that gave the user the most value in a single download. Other files, versions, and packages fell to the bottom of the page -- available for the users that absolutely need it, but far from distracting for the users that just want to get their work done. Reducing choices makes the site more useful, not less.

We did the same thing with RSS feeds, though maybe not as successfully. I couldn't figure out why any site needs to publish RSS 0.91, 0.92, 1.0, 2.0, and Atom -- doesn't this make confusing terminology dramatically more confusing? -- so I just chose Atom. It turns out that many people seem to recognize the term "RSS" but not "Atom" -- we got a bunch of requests for per-component RSS feeds, which are already present, labeled as "Atom Feeds." And boy, wasn't I surprised when I went to test the Atom feeds in NetNewsWire, and found that the current stable release of NNW -- 1.0.8 -- shows a "Feed not found" error when you try to subscribe to an Atom feed. Huh!? The 2.0 beta does support Atom, but it's pretty dumb that 1.0.8 gives a "not found" error -- what it really means is, this format isn't supported. I'm amazed that, a full year after Blogger switched to Atom-only feed support, any popular feed reader would give such a confusing error message for Atom, not to mention failing to support Atom in all current releases.

We could have reduced more, and we should have. I was joking with Jason that while many software releases proudly announce, "Now with seventeen new features!" I'd be happy to put out a release that proclaimed, "Now with seven fewer features!" If you think you've removed everything you can, try harder. You'll be glad you did -- the site gets more usable as it gets simpler.

Web tools

We made very heavy use of Mantis and Basecamp while developing CodeZoo, and I just can't imagine doing another project without them both.

Mantis is my bug tracker of choice; it is a free, web-based PHP/MySQL application. If you're not using a bug tracker on a development project, you should really give it a try; and if you're using Bugzilla, please, get help. Bugzilla is browser-based masochism. Don't try to keep track of issues in email; put them in a database. Mark each issue with a priority, and agree on a priority level above which an issue must be fixed to launch. Bugnotes are a huge savior when the going gets tough. Being able to assign an owner to an issue, and hand off issues from one owner to the next with history attached, is a huge time saver. Bud Tribble, one of the first Macintosh engineers, once told me the Mac team got rid of the distinction between features and bugs, and just tracked "tasks," which is what we did, too. Why waste time arguing about the genus and species of work that needs doing?

We also used Basecamp very successfully. We had a widely distributed team (not international, like 37s, but bicoastal), and for milestones, to-dos, and ongoing discussions, Basecamp was a huge improvement over email. We didn't wind up using the file attachment feature -- we checked all files into source control, and just pointed each other to the file path -- but otherwise, we used every feature Basecamp offers. As a long-time MS Project hater, it's so nice to feel love for project software. What a relief.

Daily calls

One of the practices I inherited from XP was the idea of a daily check-in meeting. For our distributed group, we used a dial-in 800 number for a daily, 10-minute call. This was a great help in keeping people together and in touch. For a long time, two of the three people on the team had never met in person, so at least hearing the voice of the other person helped them feel connected and personally involved. Some days, the call was pretty useless; most other times, we caught things that had fallen through the cracks or came up just through chatting. I'm a big fan of some supertextual connection for at least a few minutes a day; smileys and frownies are no substitute for the enthusiasm or anxiety you can hear in someone's voice.

Small teams rule

At my last company, the engineering team started with eight people breaking ground on the first day, and grew substantially from there. For CodeZoo, we had three people for most of the project, and a fourth at the end. I took care of writing up the idea, making the business parts happen, doing quality assurance, writing the text for the site, and being the "catkiller" in the room. (At Organic, where I once worked, the term "catkiller" came out of a client project in which the interface showed a black cat from the earliest version of the design. Each time we did a design review, internally or with the client present, someone would ask to have the cat moved from one place on the screen to somewhere else on the screen. The cat became the focus of many discussions and many more revisions. For the final review, the highest authority at the client finally saw the interface for the first time, and the sum of his comments was, "Love it. Kill the cat." This became a new rule at Organic: have the catkiller in the room early, and you'll save a lot of heartache.) One engineer did everything with the frontend and about half the database work; the other engineer did the rest of the database work and wrote the "crawler" that went around the net finding new components for us to include. Towards the end, a graphic designer joined (which should have happened much earlier; it didn't for practicality, not preference). That's it.

The rule at 37signals, and Apple, and Amazon, and at many other teams whose work I respect, is the same: keep the team as small as possible. Metcalfe's Law, that "the value of a communication system grows as approximately the square of the number of users of the system," has a corollary when it comes to project teams: the efficiency of the team is approximately the inverse of the square of the number of members in the team. I'm beginning to think three people is optimal for a 1.0 product release. Going back to "reduce," start out by reducing the number of people you plan to add to the team, and then reduce some more. (As Jason points out in his talks, this means each person on the team needs to have many skills.)

Domain name transfer

We wound up purchasing the codezoo.com domain name from someone who owned it already, and in the process, I had a brutal introduction to the world of domain name registrar transfers. In the name of openness and deregulation, ICANN allows many companies to register a domain name, and then manage the registration of that domain, for you or your company. The past owner of codezoo.com had registered it with a registrar named Omnis, and O'Reilly manages its domains with another firm. We had to transfer the name from Omnis to our registrar in order to use it. Of course, that doesn't benefit Omnis at all, so they did everything possible to prevent the transfer from occurring: holding requests for as long as they could, directly lying to us on the phone about it, day after day, and eventually refusing to take our calls at all unless we wanted to sign up for services from them. Towards the end of this process, when we had launched the site as codezoo.net since Omnis had prevented us from launching with the name we'd bought, I realized: "Wait a minute! I'm dealing with the phone company, that's what this is!" Ma Bell is gone, and in her place, the new locus of bureaucratic metastasization is domain registries. I guess the Internet really has grown up! Don't do business with Omnis, and if you plan to transfer a domain name, allow more than a month for the whole thing to happen.

CodeZoo was a very enjoyable project, and I think it shows in the results. We learned a lot from 37signals, both in their approach to building software and from using the software they make. I'm hoping we can continue to improve the site, and the way we make it, and pass on whatever we learn in the process.