Brent Simmons started an email group discussion about creating a new mail client in Cocoa. You can read the discussion here. So I’ve decided to describe how I use mail. Please forgive the overuse of the first person singular, but I’m essentially describing a user profile of myself so it’s unavoidable.

I try to follow the inbox zero (action-based email) philosophy as much as possible. I file most messages in a folder called archive. I do, however, have another folder called receipts for online purchases and a couple of other folders for professional topics. I try to keep my inbox clean, but usually have 1 to 5 items that are read but in my inbox until I’ve acted on them.

I am not a full-time independent software developer. I do release software in my spare time and work full-time in the enterprise Java space. So I don’t have to trudge through as many emails as some people. I also rarely subscribe to mailing lists, and when I do, I always subscribe in digest form. After reading a digest from a list, I delete it. I do not save it so I can search it in my email client. The list is archived on the web and if I need to look for something I look for it on the posted archives.

I am interested in the way email is presented and managed. Here is how I currently use Mail. I do not use three pane mode. I minimize the mail windows as small as possible. If I want to read a message, I double click it. I then right click on the message and file it in a folder to archive it once I’ve read it.

My main problem with using mail this way is it is not easy to change from the inbox to another mail folder. When I do, I create a new view window (File -> New Viewer Window). I then make that window larger and use it to search for old messages.

As you may have guessed, I am interested mainly in the UI and information hiding. My current inspiration for product design would be ZenWare.

M@

Software by it’s very nature, tends towards complexity.

When a program is in it’s infancy, with few features and few lines of code, adding a new feature can usually be done quickly. But as the program evolves, although adding a new feature may still be quick and easy it may cause little side effects in other parts of a program. So adding the new feature may not take long but adjusting the rest of the program so that everything flows properly will take time.

Think of stable software as a calm pond, with a surface smooth as glass and adding a feature is like throwing a pebble in that pond, which causes ripples that need to be dealt with. One of the things that distinguishes a junior from a senior programmer is that the junior programmer will not foresee these ripples and will think he has completed his task prematurely.

To illustrate what I’m talking about I’m going to talk about a new feature that will be in the next SunFlower release.

The Problem

Snapshots in SunFlower can pile up, and eventually you need to delete some. To delete a snapshot you must control-click on the snapshot and choose delete.

This interface works but is kludgey. It’s not convenient when you need to delete many snapshots because control-clicking on each snapshot is slow and cumbersome. There is definitely room for improvement in this interface.

The Solution

The solution is simple. Add a delete button that appears when the user positions the mouse over the snapshot. This is an established interface, it’s how Safari deals with the close buttons for tabs without making the interface feel cluttered.

The Ripples

So what were some of the ripples caused by adding the delete button?

Because the user can navigate the snapshots with the keyboard, we need to detect if the mouse is over a snapshot after keyboard events. We cannot simply use mouse move events to detect if the delete button should be shown. ((Ripple.))

In this case most of the ripples were design based. Snapshots have a state of being “read” or “unread”, and an image is displayed on the top right corner when the snapshot is brand new.

Having two images represent different things with varying red colours is not good. So the unread marker image now needs to be changed. ((Ripple.)) I could change the colour of the unread image to green but I’d prefer that both images weren’t the same shape to prevent confusion. ((Ripple.)) The delete button has nice shading and puts the unread marker image to shame so the ante has been upped. ((Ripple.))

Addendum (Aug 03 2009)

Brent Simmons describes this concept in more detail in a recent blog posting.

It’s not enough just to write the basic functionality and add a menu item that runs it. Even a feature as simple as this one requires some up-front thinking, some design.

…

The code behind the feedback window is, again, bigger than the http-call code. (By now you’ve gotten the idea that the core functionality of a feature is often the very smallest part.)

Over time having good documentation can have subtle effects on the flow of what you produce in an environment and how enjoyable it is to program for that environment. As someone who programs in Java and in Cocoa it seems worth it to point out the differences in how the API documentation is laid out. I’m gonna explain why Apple’s Cocoa docs are better than Sun’s (uh, I mean Oracle’s) Java docs, and why I always dread having to look something up in the Java API.

We will be comparing JWindow with NSWindow. Both documentation sources are created with document genertation tools. Apple uses HeaderDoc for their API and Sun (errr, Oracle) uses JavaDoc for their API.

Method Overview

The first noticeable and most important difference is the method overview for each. Java documentation is in alphabetical order. Cocoa documentation has been organized into logical groups. Organization is important because the most common thing you do as a programmer is look for a method that does what you want to do. When you are unfamiliar with the methods on a class or haven’t used the class for a while all you know is “I want to do X”. Grouping the methods into categories of actions makes it easier for the uninitiated to find what they are looking for.

Method documentation in Java


Method documentation in Cocoa

You might be thinking “Hey, wait a minute, the cocoa documentation looks cleaner but where are the method parameters, return types and method description?” The method parameters and return types aren’t that important when you’re looking for what will do the job. If you need to know them you can click on the method to get more detailed information. The method description is important and is displayed when you mouseover the method link. By removing visual clutter the Cocoa documentation makes it easier to find what you need.


Displaying a method description with a mouseover

Super class methods

Super class methods are handled differently also. In Cocoa, they simply aren’t there. If you want to see the methods on the super class then you must navigate to the definition of the super class. In JavaDoc, however, there is a less than useful dump of all the methods of all the super classes in a highly unreadable form. This can create a lot of visual garbage that you have to scroll over.

A summary of super class methods in JavaDoc

Conclusion

The point here is a point that has been made in the past “API Design Matters”. Not only should it be well documented, but that documentation should be an easy to use reference.

I’ve decided to move recently and I decided it was important to walk to the grocery store. I also took the location and plugged it into walkscore.com. To make it easy to quickly determine how easy it was to walk to a grocery store I created the following image.

The center of each circle represents a grocery store. The entire circle represents where it would be convenient to walk to that grocery store. This is fairly subjective and I thumbed it. It also doesn’t take into account hills, and less pedestrian friendly roads, but it does provide a quick and easy way to determine if a location is close to a super market.

Although the primary topic for this blog is Macintosh development, user interface and experience are also becoming a main theme. Therefore I thought it would be valuable to outline the technical issues I had viewing the Microsoft 2008 tech-ed conference presentations.

Even if your focus is primarily as a Cocoa (insert other programming language here) developer, it’s a good professional development strategy to get an overview of the technological offerings in other ponds. You might take an idea or concept and apply it to what you’re working on, or you might see what doesn’t work well and avoid the same mistake.

I heard about a conference called Microsoft tech-days and planned on watching presentations on the Windows mobile technology for a day. We all know the iPhone is the hot ticket item to kode for these days, but to get a sense of perspective, I thought it would be interesting to get an overview of Windows mobile.

Due to poor registration the live talk was canceled. However, I did receive the conference swag bag in the mail. It contained some obligatory evaluation software and a set of DVD’s for the 2008 Microsoft tech-ed conference (Cocoa translation:tech-ed is roughly equivalent to the WWDC).

These discs sat around the house for a while and over the holidays I decided to start looking at them. I yanked out my work laptop (not a Mac) running Vista with all the latest updates, and put the first disc in. An HTML page (Default.htm) on the DVD automatically loaded up in my default browser, Chrome, so I opened the URL in Internet Explorer. Viewing Microsoft web pages in a Microsoft web browser is generally advisable. ;)

 

This is where things got interesting. I clicked on the “view sessions” button and I was prompted to install Silverlight. I was pretty sure I had the latest version installed because I always install the latest updates on this machine, but I clicked on the install Silverlight button anyway and got the following page.

 

The page states, “The site that you visited was built for an earlier, beta version of Silverlight – not the current one”. So I have the latest Silverlight (version 2) but I can’t view the page because the page burnt onto the DVD specifies version 2 beta 2.

No problem, I’ll manually browse the disk; the Silverlight page is just an index of all the sessions.

 

Of course every directory is three characters long, except PPTX, it gets an extra character, so more digging is required. Looking in the ARC folder there are a bunch of other ARC folders with number codes appended to the name (ARC201, ARC202,…). Inside each of these directories is a slides directory with a bunch of jpeg files (Slide1.jpg, Slide2.jpg,…). The second slide contains the title of the talk. Finally, I know the title of a talk, and I know that ARC probably stands for Architecture. This is a little thing, but big things can be the summation of the little things like this.

I looked at the HTML code and ancillary files until my curiosity was satisfied,(eventually I determined that WIT=Women in Technology, KEY=Keynote, MBL=Mobile.) then I started doing web searches about the issue I was having with Silverlight not displaying the page.

A blog posting by Tim Heuer entitled TechEd 2008 North America DVD Update explains that yes, it was a big goof.

“In hindsight, choosing to burn a copy of a Beta 2 application to a distributable disc was not a good idea. We admit that and apologize. Hopefully you can see that the content is the king here and that is not lost or unusable. Thanks for your patience while we created the content map based on your feedback!” — Tim Heuer

The blog posting also provides a downloadable PDF with an index for all the sessions. This document also explains that you need to click on the WMS (Windows Media Skin) file to watch the talk. The WMS file uses javascript with begin and end times for each slide and plays a WMV audio file synchronously.

Conclusion

Let’s take a look at my entire educational experience:

• The live talk was canceled.
• The DVD didn’t work properly because it was hard coded for Silverlight beta 2.
• Unreadable three character directory names.
• I had to do research to figure out the best way to view the sessions and get an index of the sessions.

So far I’ve spent more time tinkering with files and web pages in order to view the tech-ed conference than viewing the DVD material. Something that should be drop dead simple, putting a bunch of video files on a DVD for developers to view, became an ordeal. Creating WMV files with the jpeg slides as the video track would have been much simpler. One file with a video and audio track for each talk.

Instead Microsoft decided to use a WMS file to create a custom video player; with chapters created by using a javascript file and a bunch of jpeg files. Having chapters is a good idea, unfortunately the ability to watch the talk in full screen mode was sacrificed (another one of those little things).

I can confidently say that Microsoft does not have their act together, and will not anytime soon. But some of these talks do look interesting. So thanks for the fish free DVD’s.

So far I’ve enjoyed Miha Kralj’s talk on architecture entitled “Architectures: The Good, the Bad and the Ugly”. In it he discusses many anti-patterns and lets the ugly out of the bag on Sharepoint; apparently it uses stored procedures instead of foreign key constraints for referential integrity.