AODC day 1: UA Design and Implementation for iPhone Apps

This week I’m at AODC 2010: The Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. Crocs and docs, what more can you ask for! (Chocs, I hear you cry? Hear hear!) This post is my summary of one of the sessions at the conference. The post is derived from my notes taken during the presentation. All the credit goes to Joe Welinske, the presenter. All the mistakes and omissions are my own.

Joe Welinske presented the last session on Wednesday, titled “UA Design and Implementation for iPhone Apps”. I was excited to hear what Joe had to say on this highly topical subject.

During the presentation Joe passed around his iPad, much to the delight of the audience. On his iPad were two of the applications (apps) that he has been working on with his clients. His presentation discussed some aspects of the UA (user assistance, or help) and UI (user interface) for the apps:

Joe also pointed out an iPad application that you can use to do presentations where the content is stored in DITA:

  • Nomad

Joe’s introduction to his presentation

Joe set the scene by describing the world of mobile devices.

The number of mobile devices is growing fast, and the way that people consume applications is moving more and more towards mobile devices.  The environment is becoming very complicated for application developers, given so many different platforms and numerous different devices within each platform.

Look at the different types of gestures made available by the iPhone, iPad and other touch devices. The multi-touch features, such as double-tapping on a certain part of the app, make certain things happen. How do you make this obvious to the user?

Mobile devices typically have small screens. So they have more complex UIs, to offer users a rich feature set.

There are literally hundreds of thousands of apps available.

AODC day 1: UA Design and Implementation for iPhone Apps

AODC day 1: UA Design and Implementation for iPhone Apps


The set of tools Apple put together for the iPhone app developer (Interface Builder) makes it easy for Joe, as UA developer, to see what the developers are be doing and how their design will fit in with his user assistance work. In particular, he makes use of the wizards and simulator provided by Interface Builder.

These tools mean that Joe can experiment with different types of user interface without creating an entire application and going through the application approval process. He can learn about the possibilities and keep up with what the developers are doing, so that he can then provide his user assistance content quickly when the developers send him the code base.

Joe showed us some screenshots of the Interface Builder (IB). Pretty interesting. Joe uses it to experiment with different types of help text, then he runs the simulator to see what the user would see when using the app and the help.

The iPhone SDK (software development kit) is free. You can run it on an Apple Mac. You don’t even need an iPhone.

UI text

Joe showed us the places the iPhone provides where you can put UI text. Examples are: labels, placeholders, alerts, tab bar text, segmented controllers, error messages, and more.

On a mobile device with such a small screen, every single word and every single phrase is important.

An interesting point: This makes it different dealing with management, who traditionally measure progress by number of pages etc. Here you spend days going over exactly the right word.

Coding language

Almost all iPhone developers use Objective-C, and will be doing so for the foreseeable future. As a UA developer, you should get to know Objective-C, and become familiar with your editing environment so that you know where certain objects appear. That way, you’ll get to know the places where your text will appear.

UI text on the Timewerks app

Timewerks is one of the apps Joe has been working on for a client. It’s an app for contractors (IT consultants, building consultants, etc) to keep track of their tasks. It provides a timer that will track the amount of time they spend on a task. They can then immediately record the time and send an invoice by email.

Joe showed us some examples of supporting UI text he’d created and changes to the wording on buttons etc, that improved the user’s understanding of what was happening. A very small change to UI text can have a big effect in improving how the user understands what’s happening.

UI text on the QuickOffice app

This is another of the apps Joe has been working on. Again, small adjustments can make a big difference. For example, in the Excel part of the application, they changed the words “Font format” to “Text format” and “Cell background” to “Background color”. This helped a number of users who were not Excel users, but were using the iPhone app.

Quick start guide for the Timewerks app

Next Joe walked us through a quick start guide he had created for the Timewerks application.

He pointed out that you need to create a help system that fits with people’s expectation of dealing with a mobile application. They simply expect a minimal amount of content. Yet you want to give them enough information. Joe came up with a quick start guide, with a tab bar at the bottom.

See the human interface guidelines for the iPhone. They’re great! But there’s nothing in there that’s relevant to what we do. Joe remarked that someone needs to write a guide for user assistance.

You must make your vocabulary one that people are familiar with, such as using the words “touch”, “pinch”, “swipe”.

Where possible, keep the content above the fold i.e. it should fit onto one screen. Joe’s content actually extends over two screens. He’s not completely happy with that, but at least it does give people the information they need.

Server-based help pages

The help pages are hosted on a server. If someone is online, the phone picks the content up from the server. If they’re not online, it uses a cached version.

Another point worth knowing is that the help content was viewed as part of the app. So Joe did not need to get it approved by Apple as a separate app.

Joe discussed the complexities of getting your content to look right and fit onto the iPhone screen. The content is basically HTML. The iPhone web browser is based on Safari. You can use the “viewport” tag in the HTML header to format the content for display on the iPhone.

<meta name="viewport" content="width=device-width" />

Other browsers will ignore this tag, but the iPhone will respond to it.

BTW, says Joe, you can use this same “viewport” tag on your own website, to have it appear nicely on the iPhone.

Web-based video tutorials

Joe likes the idea of YouTube-type tutorials for iPhone apps. He thinks that this is the type of medium iPhone users want to use for this type of information.


There are almost certainly going to be some synchronisation tasks involved, to move data between a desktop application and the mobile app. Joe pointed out that you should make an effort to ensure some consistency in the UI of the desktop syncing app and the mobile app.

More about iPhone help

Interesting: MadCap Flare’s latest version has an output type to generate iPhone help.

Joe remarked on the way Flare and other authoring tools are going: The help output is not based on the native iPhone UI. Instead, it’s basically HTML and CSS, made to look like the native iPhone UI. The advantage is that you can use the content in different platforms. Whether this is the best way to go, is still a question.

Joe also showed us the iPad user guide. The documentation UI exactly mirrors the UI of the iPhone/iPad itself. It’s based on HTML, CSS and sophisticated JavaScript created by the Apple developers to look exactly like the native iPhone/iPad UI.

Developing help for the iPad

The iPad presents four times the screen real estate. iPhone app vendors are already working on apps for the iPad. For example, QuickOffice have already made an iPad version — they’ve scaled everything to make it work well on the iPad.

There’s a new version of the iPhone/iPad SDK. It has a new iPad simulator too. You can develop iPhone and iPad apps using the same SDK. The main difference is that you have more screen real estate on the iPad.

What about Android?

Joe talked about the fundamental differences and similarities between the iPhone SDK and Android:

Android is based on Java.  There is a simulator too. The things you can do for UA are essentially the same as for the iPhone: Web-based help pages, native help text, different types of UI text.

The main difference is that it’s much more complicated to figure out how to do that for Android. There’s no unified development environment. It’s not packaged, as Apple have done. Most developers use Eclipse.

Joe ended up hiring an Android programmer to sit down with him for 3 hours and go through the whole scenario with him.

Another big difference is that you’re dealing with multiple Android Virtual Devices (AVDs). Essentially with Apple, you only have one version of the iPhone or iPad. With Android, virtually any type of device is possible. It doesn’t even need to be a phone. So you’re dealing with many different shapes.

Another difference is that in Android, all the UI text is in an XML resource file. For example:

<string name="start">START!</string>
<string name="retry">RETRY</string>

My conclusions

This was an awesome window into the world of iPhone and iPad UA development. It sounds like a lot of fun. Thank you Joe.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 14 May 2010, in AODC, online help, technical writing, WritersUA and tagged , , , , , , , , . Bookmark the permalink. Leave a comment.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: