There are two primary use cases for accessing documentation. One is immersing yourself in guides to learn the theory behind part of a framework. The other is quick API reference. The latter is where the current documentation workflow in Xcode (the documentation window and Quick Help window) has lots of room to improve. Here are the main problems with the current interaction model:

• Documentation takes you out of your programming flow. Once you need to access documentation, you have to open a heavyweight window that’s far from the code you’re writing, and remove yourself from the context of writing code.
• Developers need to manually move information from the documentation window to their code and often vice versa. If I’m working with a particular class in code and need documentation on it, I occasionally have to tell the documentation window about that class. When I find the particular bit of information I’m looking for, be it a method name, argument, etc, I have to manually move that bit of information to my code. This makes for a fairly inefficient workflow.
• For methods that can only accept a small set of arguments, an additional disclosure interaction is required to view the set of arguments. If I want to set a view controller’s modal presentation style, for instance, I need to click a hyperlink from the documentation on modal presentation style that takes me to another webpage in order to see the various styles I can set.
• The API documentation doesn’t make use of images in the cases they’d be appropriate. Paragraphs of text are written to describe what can often be more effectively conveyed using images.

• Developers have to access documentation because the autocompletion list often isn’t helpful. Take the autocompletion list for an instance of UIViewController, for example. Every method that can possibly be understood by a standard view controller instance is listed there – even delegate methods for unrelated classes.

My Proposal

I propose that API documentation is combined with autocompletion. Anywhere in your code where it would make sense to show an autocompletion window, we show this window instead. Rather than show a set of seemingly random methods, we instead show the methods the particular class responds to, with a mechanism to view methods and documentation for the superclass. You can use the cursor or the arrow keys to read the documentation for particular methods, and when you hit Return, the method is added for you and syntax surrounding the method is adjusted appropriately. For instance, if you begin the statement with a call on a class object and you choose an instance method in the documentation window, an “alloc” will be added accordingly.

The list on the left consists of methods and properties the class implements, grouped by type of development task. Simply scanning through this list gives you a good understanding of what the class does and how to interact with it.

Compare to the system documentation that groups functionality into properties, instance methods, and class methods (which aren’t helpful groupings for finding functionality in a class) and sorts items in those sections alphabetically:

Sidenote: Ingredients deserves credit for being the first documentation viewer I’ve seen to group methods by task in the source list. Task grouping is one of the main features that makes it such a pleasure to use compared to Xcode’s viewer and other third-party documentation viewers.

Dragging the window away from the code it’s inspecting will un-anchor it and let you use the window in more of a back-and-forth reference fashion (much like how Xcode’s documentation window is used today). The window loses its arrow and a close button and search field appear. The search field will let you search for any symbol in Cocoa or Cocoa Touch (depending on what your project is targeting). Search results appear in a menu below the search field, so you keep your context as you search.

In some cases, we can do even better than autocompleting method and property names. The window gets even more useful in the case of setting a variable that only has a small set of arguments it accepts.

A third pane will appear below the documentation with a list of possible arguments, showing images when appropriate. You can arrow over to the argument list, hit Return, and the method name, along with the argument will be entered into your code.

Here are the current set of steps for setting a view controller’s modal presentation style, if you aren’t aware of the name of the property:

1. Start typing your statement with the name of the view controller.
2. Open the documentation window.
3. Search for UIViewController.
4. Click modalPresentationStyle under the tasks section of the webpage.
5. Copy “modalPresentationStyle” into your code.
6. Click UIModalPresentationStyle to get the list of styles.
7. Find the desired style and copy it into your code.

The steps for accomplishing the same task with this interface:

1. Start typing your statement with the name of the view controller.
2. Hit the keyboard shortcut for showing the autocompletion window.
3. Select modalPresentationStyle in the source list.
4. Select the desired style and press Return. The entire statement will be entered in your code.

If the developer already knows about the method or property name, Xcode can still be helpful by providing a focused, rich interface for choosing a value.

Other Contexts

The contextual disclosure type of interaction is also useful in other contexts. For example, when I want to assign a graphic in my project to a new variable, my interaction with Xcode generally follows this pattern:

1. Start typing out the instantiation statement.
2. Scroll around in the Groups & Files list looking for where the particular image is nested.
3. Click the image to see a preview of it to make sure it’s the image I want.
4. Copy the image’s filename.
5. Press the back button to go back to the code I started at.
6. Paste the filename and add the required syntax around it.

What if while you were in the flow of instantiating an image variable, Xcode showed you a menu with filenames and thumbnails of all the images being bundled with your target?

Now the steps to instantiate an image variable are:

1. Start typing out the instantiation statement.
2. Hit a keyboard shortcut to show the thumbnail menu.
3. Choose your desired image and hit return. The rest of the syntax will be entered for you.

Another example is setting a view’s autoresizing mask. An autoresizing mask specifies how a view resizes as its parent view resizes. Interface Builder has a great interface for configuring one of these. You can click on a view’s edges to specify which edges should be anchored to the edges of the superview. You can also click inside the view to specify whether it should resize vertically, horizontally, both, or neither.

As you click around adjusting those settings, there’s an animation of a view getting resized as its parent view resizes, giving you instant feedback showing you how your changes will affect resizing of the view.

The interaction for setting an autoresizing mask in Xcode is second-class in comparison. Regardless of if you use property syntax or message passing syntax, the autocompletion window won’t give you anything useful. You have to go into a documentation window outside of your flow, search for autoresizingMask, click to see the values that can be passed in, know that you have to bitwise OR these together, know the syntax for bitwise OR, and construct a long statement with values copied from the documentation window.

Like Interface Builder, Xcode should know what an autoresizing mask is and show you a usable interface for setting one.

In this post, I’ve explored just a few use cases and improvements. But there’s nearly endless potential for an Xcode that truly understands the frameworks being used and provides effective interfaces for interacting with them.

The Design

For comparison:

Toolbar

Display

Table Headers

Scrollbars

Checkboxes

I’m closing the comments so I don’t have to sort through spam. If you’ve got feedback, feel free to hit me up on Twitter.
 

I’ve spent the past year redesigning a particularly complex application with my primary focus being on reducing complexity. In this article, I’ll go over some of the issues surrounding complexity and techniques that can be used to manage it.

Progressive Disclosure

Progressive disclosure is the most popular means of managing complexity. The idea is that clutter and cognitive overhead can be reduced by hiding less frequently used elements behind some avenue of accessing those elements, like a mouse click or a keyboard shortcut. It requires that the designer accurately determine which elements are frequently and infrequently used and to what degree.

Quite a bit of care needs to be put into the progressive disclosure hierarchy and the mechanisms used for disclosure. Poorly considered use of progressive disclosure can achieve the opposite of the intended effect by making the interface even more complex. As an example, Microsoft Windows has been trending towards removing the menu bar from individual windows and instead packing each function into the main interface (often using pull down menus), which has some issues. I’ll go over a few of them:

• There are inconsistent ways of accessing common functionality. The Print function, for example, is in different locations in both the application’s interface and the progressive disclosure hierarchy. The Print controls in Internet Explorer, Contacts (Windows Explorer), and WordPad are highlighted in the screenshot below, to illustrate this. Competing first-party Mac applications (Safari, Address Book, and TextEdit, respectively) have the Print function available in a consistent location – the last item in the File menu. A user who learns how to print in one of those Mac applications won’t have to hunt to find the Print function in other applications. It’s a “learn once, use everywhere” model.
  

• There’s a tendency to overwhelm the user with progressive disclosure points. The default Internet Explorer interface (with Windows Live installed) has a total of 17 pull down buttons – highlighted below. Further, all of these progressive disclosure controls require screen real estate. As more screen real estate is occupied by administrative actions, less is dedicated to displaying the actual content of the application (which, in this case, are webpages).
  

Contextual Actions

This is a form of progressive disclosure where contextually appropriate controls are exposed on a particular object. The most common implementation are contextual menus, activated on the Mac by a right-click or a control-click. While contextual menus are a consistent and useful way of revealing contextual actions on objects, they’re hard to discover, which makes them inappropriate for workflow-critical actions that necessitate greater weight in the interface.

The standard way to give these actions greater weight is to integrate them in your interface by providing the set of contextual controls in front of or near each object. Complexity is increased substantially, because the set of controls is repeated for every object on screen. We can get rid of most of this complexity by using a different progressive disclosure technique. Controls can be displayed on a single object if the object is selected, the object has focus, or when the mouse is over the object. This solves the complexity issue since there’s only one set of contextual controls being shown at a particular time, but it’s not without its downsides. Consider whether this sort of technique is appropriate for your interface before deciding one way or the other.

Alignment & Visual Hierarchy

Aligning elements in a user interface to a simple, consistent grid, will go great lengths in reducing the appearance of complexity. The use of strict alignment and a thoughtfully laid out grid can turn an interface from chaotic and overwhelming to harmonious and appealing.

Some compelling examples are the inspectors in Microsoft Expression Blend and Adobe Lightroom. While a host of factors are responsible for the Expression Blend inspector looking considerably more complex than the Lightroom inspector, the rough horizontal alignment is certainly a primary one. The horizontal alignment lines have been drawn in red to illustrate the differences.

The examples shown above also demonstrate the effectiveness of the techniques used in each interface to indicate hierarchy. The Lightroom inspector has very strong visual distinctions between section headings and their contents. Headings are prominent. Set in large type with generous padding and a relatively high contrast foreground-background color combination, sections, headings, and the relationships between them are immediately clear.

Visual Noise & Contrast

The amount of visual noise in an interface has a great deal of impact on the perceived complexity of the interface. And contrast plays an important role with respect to visual noise. Using lower contrast UI elements reduces visual noise which will often reduce the effective complexity of the interface, as you’ll see in the next couple of examples.

The Address Book UI eschews fields with relatively high contrast borders in favour of fields with borders that are only visible if the field has focus. This causes the fields to blend in with the rest of the interface. The Create Contact window in Entourage 2008 uses the standard window background color and standard text field styling which contributes to the interface looking more complex than the Address Book interface.

As another example, I’ve taken the Filter window in Aperture 2.0 and mocked up what it would look like with the transparent controls from iLife ‘08 (and parts of iLife ‘09) with high contrast edges instead of the relatively low contrast controls that it shipped with. The UI I’ve mocked up looks notably more complex than the shipping interface because of the higher contrast controls. Simply adjusting the styling of your controls can have a considerable impact on complexity.

Use of Icons

Interfaces widely regarded as complex with high learning curves are often characterized by an abundance of icons or glyphs that lack descriptive labels. When a user opens an application for the first time with an interface covered in label-less glyphs, it can be quite daunting. Every icon with a non-obvious meaning will have to be learned for the user to feel any sort of mastery over the application.

This is a difficult problem to solve. There often isn’t room for a label to sit next to an icon, and in many cases there is cost involved in replacing an icon with a label (mainly, users will not be able to quickly scan the interface for the icon). Deciding when to use an icon, a label, or both, is an art all in itself.

Nevertheless, here are some tips for those faced with this issue:

• Revamp your icons so they convey their meaning more effectively. Improve metaphors, adjust sizes, colors, etc.
• Use grouping to imply meaning. Grouping related icons together can often provide sufficient context to imply their function.
• Using progressive disclosure, place less often used icon-only buttons in a pull down menu with both icons and their labels. A nice benefit of this is that the user will learn the meaning of each icon when they use the pull down menu, and if the menu is designed to be used early on in a user’s experience with the application, you can get away with using those icons without labels in other places in the app (since the user will have already learned their meanings at that point).

Mental Models

A great way to reduce effective complexity is to align the conceptual model expressed by your interface with your user’s mental model as closely as possible. A poorly thought out model contributes to complexity by adding a significant amount of cognitive work that your users have to perform to learn your interface.

The recurrence UI in Windows Calendar, for instance, reflects the developer’s model of the task rather than the user’s model. Take a look at the second set of radio options in this screenshot:

1. What’s the “28th last day of the month”?
2. What’s the “4th last Tuesday of the month”?
3. How long did you spend trying to work that out?

These options feel complex because the language used and functionality that’s represented doesn’t reflect your understanding of repeating events. Combat this issue by researching how your users conceptualize relevant tasks so your models are intuitive. You can read more about mental models in the HIG.

Use your Judgement

Finally, use your own judgement. There are costs associated with nearly every technique I’ve listed here. Carefully consider each technique in the context of your interface and determine which are most appropriate for your application and how best to apply them.
 

For a complete list of what’s new in 1.2 and to download the plugin and framework, visit the BWToolkit website.

1. Subview autosizing: In the inspector, the developer can tell the split view which subviews should resize with the window and which should remain at a fixed size. The standard behavior of NSSplitView is to ignore the autosizing masks on the subviews and resize them proportionally as the split view resizes. This is not the desired behavior for most applications. BWSplitView honors each subview’s autoresizing mask which is easily configurable in both the BWSplitView inspector and the subview’s size inspector.
2. Constraints: Each subview’s minimum and maximum size is configurable in the BWSplitView inspector. You can specify the size in points or as a percentage of the split view’s size.
3. Collapsing: BWSplitView has powerful new collapsing functionality. A view marked as “collapsible” in the inspector will collapse when its divider has been double clicked and when the user tries to make the view smaller than its minimum size. You can also hook up a toggle button to the split view’s toggleCollapse: action which will collapse or expand the subview using Core Animation. The split view takes care of synchronizing its state with the toggle button, so the button never shows the opposite indication.

The reason I call the split view “codeless” is that for the vast majority of use cases, the developer will not have to write a single line of code to get the split view functionality they desire. For other use cases that do require something out of the ordinary, the developer can set themselves as the delegate on the split view and implement any relevant delegate methods.

In the video below, I create iCal’s split view layout, with maximum and minimum sizes for subviews, subview collapsing with animation, and proper autoresizing behavior, all within Interface Builder – and it takes less than 3 minutes.

 
I’d love to hear your thoughts on the split view and any ideas you may have for improvements. Drop me a line or file a bug.

And a big thanks to Fraser Kuyvenhoven for developing the split view’s resizing algorithm.
 

Source Code

To make this process simpler, a new item has been added to the plugin to allow you to easily specify a toolbar item’s identifier in Interface Builder. This item can be used with standard toolbars as well as selectable toolbars.

As for other improvements, the size of the framework bundle has been reduced by 40% by using Apple’s TIFF compression instead of Adobe’s and a few bugs have been fixed. See the release notes for details on the particular bug fixes.
 

Source Code

BWToolkit is a BSD licensed plugin for Interface Builder 3 that contains commonly used UI elements and other useful objects. Using these objects is as simple as dragging them from the library to your canvas or document window.

When I first heard about the plugin architecture in IB 3, I saw a huge potential for improving the developer user experience and lowering the barrier to entry for developers who are new to Cocoa. I hope to have accomplished that with this plugin. Read on for details regarding the items in BWToolkit and screencasts showing how they work. Be sure to read the release notes if you’re interested in downloading the plugin. It has installation instructions and known issues that users of this plugin should be aware of.

“No Code” Preferences Windows and Tabbed Sheets

With the Selectable Toolbar item in this plugin, you’ll be able to create preferences windows and tabbed sheets without writing a line of code. Using BWToolkit to create a preferences window or a tabbed sheet is radically simpler than conventional means. You don’t have to write a controller class or fiddle with plists and multiple nib/xib files. It’s drag and drop. Watch the videos below to see it in action.

Transparent Controls

BWToolkit contains a suite of controls for transparent windows (or HUD windows). Provided controls include a button, pop-up button, check box, slider, text field, text view, table view, and a check box cell for a table view. If you find yourself needing a much wider array of controls than the ones available here, a standard panel may be more appropriate for your particular interface.

Button Bars

The plugin includes an anchored button bar, anchored buttons, and unanchored buttons. An anchored button bar is one that is placed directly below a view (in other words, anchored to that view). Anchored button bars often appear at the bottom left of windows below source lists (like in Mail.app), below a table view with padding below the bar (like the Network pref pane), or run all the way across the bottom of the window (like in AppZapper). The anchored button bar library item handles all three of these modes.

Unanchored buttons are usually placed below a table view with a bit of padding separating the view from the buttons. They’re often configured to have a plus button beside a minus button. The unanchored buttons are similar to “Gradient Buttons” in Interface Builder, but tweaked to aesthetically replicate the +/- buttons in System Preferences. For instance, when a button is disabled, only the glyph dims, so the group of buttons remain a visually cohesive unit.

Using the anchored button bar and the gradient split view included in the plugin, you can easily create a Mail.app style interface. When an anchored button bar is dropped in a vertical split view, the split view is automatically configured to resize when the user drags the resize handle on the button bar. It’s also configured to keep the source list the same width while the window is resized – the standard split view behavior is to resize all of its subviews. Lastly, the left most view is constrained within a minimum and maximum width (which is configurable in the button bar inspector).

Bottom Bars

With this plugin, you’ll be able to add a bottom bar to a window and it will appear on your canvas. This makes sizing and placement of controls on or around the bottom bar a trivial exercise. There are four bottom bars to choose from: mini size, small size, regular size, and one for sheets.

There are also some controls for bottom bars included in the plugin. You’ll find plus and minus glyphs for regular size Round Textured buttons, a text field with an inset (or etched) appearance, and a textured slider. The textured slider comes pre-configured with the two most popular indicators in Mac apps: speaker and photo. If you opt to use them, you’ll find that the click actions for the two indicators are conveniently already hooked up to the slider.

And More

There are a few other items in the plugin that haven’t been listed yet or shown in a screencast: split views with adjustable divider colors, Fonts and Colors toolbar items from iWork ‘08, and a fancy gradient token field.

If you have any questions or comments, feel free to email me or ping me on Twitter.
 

Source Code