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@

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

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.

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.

Repeat after me. Keep things simple. Don’t over complicate things. This post is about quirky web design, it is not Mac specific (except for the fact that I am using Mac Safari to do all the testing); you can safely skip this post if you’re only interested in pure Mac content.

One of the sites I monitor with SunFlower is an IT company called coemergence. They updated their site recently, and ever since then the rendering of the image below started causing false positives.

The false positives occurred because the image would be rendered at slightly different sizes. The reason for this stems from the javascript code below; in particular the use of document.body.clientWidth.

var coe_image_width = 665;
var coe_image_height = 218;
var coe_width = document.body.clientWidth;
var coe_left = coe_width - (coe_width * 0.8);
var coe_center = (coe_width - coe_left) * 0.8;
var coe_multiplier = coe_center / coe_image_width;
document.write("<img src='/images/stories/coemergence/cobanner_665x218.jpg' " +
"width='" + ((coe_image_width * coe_multiplier) * 0.82) + "' " +
"height='" + ((coe_image_height * coe_multiplier) * 0.82)  + "' " + 
"align='center'/>");

What mistakes did the author make?

For one, document.body.client has no relation to the actual width of the webview, it is the size of the view port. If you squeeze this page to about 300px wide and do a refresh you will get a small image. If you then resize the window the image stays small, which is probably not the effect the author is looking for. We’ll look the other way and pretend the page doesn’t look icky when you resize it.

The designer also made the assumption that the page is fully rendered and that the last thing that will be rendered will always be this image where the height and width are being calculated dynamically.

Want to see that the result is inconsistent?

1. Load http://www.coemergence.com/index.php in a new Safari window
2. Choose Develop -> Show Web Inspector
3. Switch to the DOM tree view
4. Find the calculated height and width of the image
5. Close the window
6. Open a new Safari window (which will be the same size as the previous)
7. Repeat steps 1 to 6 and compare the results

I did the steps above and I got the following different results.

Result 1

Result 2

I’m not sure the exact reason that the sizes are different, and I don’t plan on spending any time checking, however I have two hypotheses.

1. When windows/views are created in Mac OS X the size is not exact. You could get a width of 799.99999 when you requested 800 (very doubtful)
2. The size of the variable depends on the order that elements are rendered on the page, and stylesheet elements are applied, and that order is not guaranteed.

There are many other design quirks with the page, like the fact that there is no minimum width and if you make the page narrow the search field and text resize buttons hide behind a current.

Conclusion

The calculated width and height are only slightly different and I only noticed it because I am using SunFlower to monitor the page. But that doesn’t excuse the author for making things over-complicated.

Choose a layout and stick to it. Making the width of your page a certain size and using white space is a tried and true method of web design. Don’t get all fancy pants when you could just do something simple.

Unfortunately, for this page, using an exclusion filter in SunFlower does not eliminate false positives because even though we can ignore the image, when the height of the image is different, it pushes the content text up or down.

Kode on!