Blog Archives

AODC Day 3: Converting to Structured Content

This week I’m at AODC 2010: The Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. 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 Dr Alan Burton, the presenter. Any mistakes or omissions are my own.

The first session on Friday was titled “Converting to Structured Content”, by Dr Alan Burton. Introducing his talk,  Alan showed us some “scary” pictures of the world he lives in. Scary indeed — a wall of codes. With a charming smile, he admits to being a “hardcore geek”. From the moment Alan starts speaking, we see that he has a good dose of the AODC sense of humour. 🙂

AODC Day 3: Converting to Structured Content

AODC Day 3: Converting to Structured Content

The problem that Alan’s talk addressed is this: You’re told that you need to move your content to XML. You have loads and loads of unstructured content. It’s in FrameMaker, Word, other desktop publish applications, or even more fun: it’s on paper.

Who does the conversion?

Alan discussed various options to consider when deciding who will convert the documents to a structured format:

  • You can do it yourself, if you have the technical knowledge required.
  • The company’s IT department could do it. Alan jokingly referred to the “IT Crowd” — are you happy for Moss to do your conversion? 😉
  • You can outsource it to someone like Alan. (He acknowledges with another disarming smile that there’s no-one quite like him.)
  • If you consider outsourcing the work to an overseas company, take into account that this can lead to difficulties when communicating requirements.


You need a sample of the documentation that’s to be converted. What’s more, it must be a representative sample. For example, check whether the documentation as a whole contains tables, images, special characters, mathematical symbols. If so, are they represented in the sample? For best results, you need to be given the full documentation set in the analysis phase.

Find out whether the documents comply to a template. If the answer is yes, ask how long the documentation has been around and how many authors have had a hand in it. What are the chances that it really does comply to the template?

Here’s Alan’s recommendation, assuming your source documents are in Word: Convert all the Word documents to RTF and then feed them through an analysis tool. He extracts a complete list of all styles that appear in the documents. If there is a large number of styles, you may have a problem. He is building a set of utilities that let him look at styles, special characters, symbols etc within the documents, without himself having to read each and every document. In this way, he builds up a picture of how easy or difficult it will be to convert the document.

Ask questions such as: “I see that you use italics to represent words that appear in the glossary. Do you use italics for any other purpose, such as titles or Latin words?”

Do the analysis before you choose or create your DTD, and before you buy any software.

Document the results of your analysis in detail.


After the analysis phase, you know what you have, but you still need to find out what you actually want. Things to consider:

  • Metadata
  • Indexing for search
  • Online and/or paper output
  • Cross-referencing

Markup specification

Alan creates a “markup specification”, which is a detailed requirement specification for the conversion. You need to add examples for each requirement.  This documentation provides the input into the design of your DTD.

Mapping document

Alan creates a document that maps the styles of the source document to the XML elements and attributes.  The developers will use this document to create or customise the software that does the conversion.

Checking the results of the conversion

When you receive the converted documentation, you need to check it to see if it’s actually what you want.

These are some of the problem areas that Alan mentioned:

  • Tables
  • Graphics — format, naming conventions, storage
  • Cross-references
  • Metadata
  • Forms — these are very hard to recreate in XML
  • Mathematic and scientific symbols and formulae

FrameMaker has a Migration Guide that tells you how to convert from unstructured FrameMaker to structured FrameMaker content. This is a useful tool. You can then export to XML. You do need to do some cleanup afterwards, either manually or with scripting.

You could convert from Word to FrameMaker, then to Structured FrameMaker.

Converting from Word to XML, you usually convert from Word to RTF and then to XML. Alan has done this once, in a very controlled environment and with just one document. It can become fairly complicated.

Converting to DITA is very challenging. You will probably need to split input files into different output files. It is unlikely that you can automate the insertion of metadata. You may need to rename graphics and create multiple graphics formats.

Bottom line

You will never end up with a clean result immediately, no matter what any tool may claim. You will always need to do some manual cleanup, and you will probably need to get a programmer to do some scripting.

My conclusion

This was a good, fast-paced walk through some scenarios and guidelines for converting from unstructured to structured content. I could tell that Alan has a lot more information to share. Thank you for a great session, Alan.

AODC day 2: Optimising your Content for Google Search

This week I’m at AODC 2010: The Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. 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. Any mistakes or omissions are my own.

Joe Welinske presented the last session on Thursday, titled “Optimising the Googleability of Your Content”. The subject was search engine optimisation (SEO). Joe is really excited about this topic. He thinks it’s one of the most important skills for a user assistance expert to acquire. Potentially, it also offers a good opportunity for consultancy.

SEO is complex, but we need to learn about it. Joe calls it “embracing the beast”: If people are going to be using Google, then we want our material to come out at the top of the search results.

These are the topics he covered:

  • Get all your content on a public-facing server.
  • Learn about Google Search.
  • Learn about SEO (search engine optimisation).
  • Find out how to use other search engines.
  • Create a custom Google Search for your UA (user assistance) material.

Getting your content onto a public-facing server

This is the single most important thing that has to happen: Your content has to be on a public-facing server.

There are ways to mirror your internal content onto public-facing servers. Joe talked about a few of them. Ultimately, the best way may be to migrate all content to web-based standards.

Security issues when publishing content on the web

Many organisations keep their content behind the firewall, or have privileged content requiring login. Security is a very real concern. Moving to a public-facing server may be a big change for traditional content developers, and a challenge for organisations that have up to now kept their documentation hidden from public view.

Organisations need to take a detailed look at all the help components they provide and see what can and what can’t be published on a public-facing server.

We should be aware that our users are using Google anyway, and we should ask ourselves what these users find when they do a Google search for information on our products.

We could put together examples of Google searches, to show management what people will be finding, given that they can’t find our own documentation. For sure, people will be posting information about your systems to answer other people’s questions.

Google search indexing

Note that some content will not index effectively. Joe gave some tips on the type of content that Google can index well and the type that may cause problems.

Good candidates for Google indexing:

  • Web sites.
  • Web-based help, such as output generated from Flare or RoboHelp. Note that frames may make the content less favourable for indexing. Google has a hard time making sense of content in frames.
  • Eclipse Help is a good candidate, because it’s XHTML.
  • PDF is good, because Google has put effort into indexing it. Some PDF formats may be less effective.

What does not work well:

  • Microsoft Help (CHM and HLP) — This format has some HTML but is mostly locally-installed and uses a lot of proprietary code.
  • Apple Help, Oracle Help for Java and JavaHelp.
  • Flash — Google has done some work to be able to index text in Flash files, but images and videos not.
  • Almost any proprietary markup — Google has problems interpreting it.

Bottom line: The more open standards you use, the better off you will be.

What about loss of context?

When we put together online help systems and context-sensitive help, we have control over the path the user follows. But when the user comes in via Google search, we don’t have that control.

Some tips from Joe:

  • Provide navigation elements on all pages.
  • Add branding, so that people know that they have found your site and thus the official documentation.
  • Include the date last updated and the version of the application that the help covers.

Examples of SEO

Joe showed an example of a Google search he entered. He asked how to print a calendar in Excel. The first result returned was a link to Microsoft Office Online, telling you how to print a blank calendar. This was exactly what Joe wanted to do. What’s more, the content was an exact copy of what’s in the HTML Help provided with Excel, but laid out differently. So Microsoft has their SEO sorted out, and they are mirroring local help content in the web-based help.

Similarly, he entered a Google search for printing a Google calendar. Again, the Google web-based help was right at the top of the results. Google provides only web-based content, so they don’t need to support mirroring of content.

In contrast, when you search for “print an ical calendar”, there’s nothing near the top from Apple. So Apple needs to work on there SEO in this particular context.

How Google search works

It’s a combination of brute force and extremely clever technology:

  • Brute force: Google runs a gigantic server farm in Washington, that buys electric power directly from the hydroelectric dam nearby.
  • Extreme smarts for indexing information: Google has clever and secret algorithms for ranking content.

How does the ranking work?

Joe mentioned the following factors that influence the ranking of search results:

  • Fresh and real content — The search index recognises a page as offering a solid body of information, not just fake content. This is an area we technical writers excel at. Link farms out there put together random text and try to fool Google. But our standard documentation will match up as high quality.
  • Nomenclature — We use the right terms and the right labels in our documentation. If people use these terms in their searches, our content will quickly match.
  • Links pointing to our content — In Google’s eyes, links indicate what other people think of the information on the page. When many people link to pages, this makes it more likely in Google’s eyes that this is well-respected content.
  • Google Ads — There is some indication that your pages will be better indexed if they contain Google Ads.

Joe gave us these sources as guidelines on optimising your content for search:

Joe had a number of more in-depth hints on things like:

  • Including the “robot.txt” and “sitemap.xml” files.
  • Registering your site at “”. (It’s free.)
  • Including metadata such as title, description and keywords.
  • And more. I’m sure Joe would be delighted to pass on this information if you contact him.

A tool to help analyse your pages for SEO

Of huge benefit is a tool called Go Daddy Search Engine Visibility. It goes through your pages and finds any search engine deficiencies. There are other tools that do the same thing.

Other search engines

Joe touched on other search engines, such as Yahoo and Bing. These are also important. Each has a separate registration procedure.

Getting other people to link to your site

Send people links to your content, such as sending links via email. Submit links to relevant sites. It’s a tough process and there’s no easy way to do it.

You can also think about community building:

  • Start a LinkedIn group.
  • Add YouTube videos with links in the metadata.
  • Add a Facebook fan page.
  • Tweet links via Twitter.
  • Encourage bloggers.
  • Supply RSS feeds.
  • Consider translated content, such as having even just a single page about your documentation, in different languages. Google indexes different languages too. Also, people who speak that language will at least learn about your documentation and your product. They can then click through to read the information in English.

Creating a Google custom search

It’s easy and free to register to create a custom Google search. Register your site. Google supplies you with the code you can use to put the search box onto your site. Google will index your site for you. Your search box will bring up results for your site only.

My conclusion

This was intensely interesting and full of information. I could not hope to capture everything that Joe told us. Thank you Joe! This presentation gave me a lot to think about and experiment with.

AODC day 2: What Kind of Assistance do Users Really Need?

This week I’m at AODC 2010, the Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. 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 Matthew Ellison, the presenter. Any mistakes or omissions are my own.

An aside, and a reflection of the fun nature of AODC conferences: At the beginning of this postprandial session, we noticed that quite a number of people were absent. “Good time for a prize draw!” exclaimed Tony Self. (You have to be present to claim your prize.) As usual though, even with such improved chances, I did not win the prize.

Matthew Ellison‘s presentation today asked the question, “What Kind of Assistance do Users Really Need?” He introducted his talk saying that it was a good follow-on from mine. (I had given the preprandial presentation, about engaging your readers in the documentation. I’ll blog about it soon.) Matthew now followed through with providing the kind of assistance that users really need. To do that, he says, we really need to understand our users.

AODC day 2: What Kind of Assistance do Users Really Need?

AODC day 2: What Kind of Assistance do Users Really Need?

Matthew covered the following topics in this session:

  • Background information and recent history that led Matthew to present this topic.
  • Current trends in user assistance design — what we’re doing now and what we think our users need.
  • Common traps for writers.
  • Step-by-step instructions, and whether they are the best solution for users.
  • A look at a research study that Matthew is involved in, and the results and recommendations coming from it.

Another aside: At this point Tony phoned Matthew on the mobile phone Matthew was using as a clicker! Hilarity broke out, as it so often does at AODC. Matthew, being an awesome presenter and well used to Tony’s antics, answered the phone with a grin and “Very funny, Tony” then returned to his presentation without breaking his stride.

Aims of UA

In this part of the session, Matthew took a look at the aims of UA (user assistance) or help. The principal aim is to solve problems and answer questions. Help can also make people aware of features and increase their efficiency in performing tasks.

At this point, Matthew asked us to think of the last time we had a question or problem and needed help.

I immediately thought of the problems I’d had with getting my internet connection to work at the hotel. “How do I get the hotel wi-fi broadband connection to work?”

The first 3 or 4 questions we came up with were all “how do I …”. Then a few different questions arose, such as “what is …”.

To illustrate the idea of cycles in design, Matthew showed some pretty cool pictures of bicycles 40 years ago, 20 years ago and today. The bikes of today share some design characteristics with the bikes of 40 years ago. In documentation and information design, ideas tend to cycle too. We looked at the recent trends towards FAQs and task-based help. Matthew thinks FAQs are a good thing. He showed us some examples of FAQs that work, including some from Twitter and YAHOO Groups.

Traps for technical writers

This may be a dangerous area, says Matthew. Some of the things he suggests are contrary to what he was originally taught about technical writing.

We should not:

  • Just transcribe information given by developers and SMEs.
  • Always give step-by-step instructions. Sometimes it’s enough to give just a simple hint or an answer to a single question.
  • Explain the obvious. If it’s easy for us to understand, maybe we don’t need to document it.
  • Blindly insist on consistency for its own sake.

Now there was another task for us: We had to write instructions telling people how to delete a file in Windows. Most of us chose to write step-by-step instructions. One group chose just a tip. Matthew suggested that you need a useful tip telling people to click Shift+Delete to remove the file permanently. You may also want to let people know that they can recover files deleted accidentally.

This simple exercise led to much animated debate, as might be expected from a group of technical writers. Is information ever redundant? 🙂

Matthew gave us an example of the way Apple have addressed the problem of explaining only the things that need explaining. See the iTunes help: “iTunes How To”. It contains a useful collection of tips people may need. For example, if you click “Buffer Sizes”, you get a page showing a screenshot of the buffer size dialogue and a short paragraph explaining what buffer sizes are and the implications of choosing a larger or smaller size.

Louise from PayPal

Louise is a PayPal “Virtual Agent”. You can type in questions and Louise will answer you.

Where do the responses come from? They’re composed by authors, based on typical questions asked by users. Tony Self, the organiser of the AODC conference,  has in the past signed up as a “virtual person” and helped to write such answers. As a virtual agent, you see the questions that people typically ask and then you write the answers. You can select the personality of your agent, e.g. humble and kind or quirky and arrogant.

Video tutorials

Some video tutorials are very bad, but some are good. As an example of a good one, Matthew showed us a video introducing Morae Observer. The voice is calm and make things sound simple. Each section is short. This video was created using Camtasia.

Study about the questions that people ask

Matthew has been taking part in a study at Portsmouth University in the UK. The reason for the study was the conviction that we should base our help on the questions that our users ask.

The study looks at when users ask questions and what types of questions they ask. It asks participants to tackle three tasks, each clearly explained. The explanation is about what the participant needs to do, rather than how to do it. There is a task in Word, a task using Google Maps (plan a route and view it in Street View) and a task using Flash.

The participants were not allowed to use the help. If they had questions, they had to ask the moderator sitting next to them. The moderator should answer only the question that was asked. This is known as the Wizard of Oz method.

Matthew and the university team used TechSmith Morae Observer to record everything that the participants did, including audio and video. This allowed them to analyse the participants’ actions and to draw conclusions.

The equipment they needed was simply a laptop with Morae installed, plus a webcam and microphone.

Results of the study

Note: Matthew explained that the results are only just becoming available. He can show us only partial, interim results at this stage. Also, I had to jot down the figures from Matthew’s live presentation, as they were not available at the time the slides were printed for our handbook. I’ve done my best to get them right. Matthew will publish the final results later.

The study classified the questions that users asked into 7 categories:

  • Meaning (What does this mean)
  • Reason (Why is this happening, or why should I do this)
  • Confirmation (Is this what I should be doing)
  • Location (Where do I go to do this)
  • Task (What do I do now, or how do I do it)
  • Response
  • Identity

Based on 7 participants out of 20, here is the number of questions that fell into each category:

  • Meaning: 8
  • Reason: 3
  • Confirmation: 74
  • Location: 27
  • Task: 49
  • Response: 3
  • Identity: 3

Participants often had trouble framing the question. Imagine how difficult it would be for them to ask the question online instead of to a person.

There was a surprisingly large number of questions in the “confirmation” category. Some participants often asked for confirmation or affirmation.

There were very few questions that fell into the reason, identity and response categories.

Conclusions — interim only:

  • Tasks are the most common question type.
  • Location is the key to solving the problems.
  • Meaning and reason are not very important in this particular study.

Matthew will publish the final results when available.

Matthew strongly encourages us to do a similar exercise. It is hugely enlightening to see how people tackle a task and the questions they ask.

My conclusions

This session was a lot of fun, especially because of the interaction between us and Matthew, and because of the lively discussions that arose. I’m looking forward to seeing the full results of the study and will publish a link as soon as it’s available. Thank you Matthew for a very interesting session.

AODC day 2: A Beginner’s Introduction to DITA

This week I’m at AODC 2010, the Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. In this session, though, we’re dealing with wolves, not crocodiles. 😉 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 Suchi Govindarajan, the presenter. All the mistakes and omissions are my own.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Suchi Govindarajan had a catchy title for her talk: “Who’s Afraid of the DITA Wolf?”

At the beginning of the session, Tony Self handed out some pretty coloured squares of paper to each of us. Intriguing! The coloured paper was soon explained. Suchi started by telling us a story about origami. Of course, this set me wondering what this origami had to do with DITA! Good start.

Suchi said that she found it really amusing that she was here talking about DITA. About a year ago, she was totally baffled about DITA. Then she attended a course given by Tony Self. Now she’s here to give a beginner’s view of DITA.

She led us through the steps to make an origami pelican, following the step-by-step instructions in her slide show. I’m hopeless at things like origami, but nevertheless I managed to follow the steps (with help from my neighbour) and make something resembling a bird.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Next, Suchi showed us some text about origami: an explanation of the theory of origami, an investigation of the maths behind origami, and other theoretical scripts about origami. She explained how different texts have different purposes, and not all are step by step guides, and not all are useful to a beginner.

DITA introductory material

What did Suchi’s origami demonstration have to do with DITA? She showed us some introductory material to DITA, pointing out how the texts were full of words and terms that a beginner would not understand.

So Suchi has written her own definition of DITA, specifically for beginners:

DITA is a standard for technical documents that’s designed to be used with XML. It comes with some free publishing tools.

We already know DITA

As technical writers, we already know much about DITA. Suchi showed us how a number of the concerns DITA addresses, and many of the terms used, have been part of standard technical writing for years. Examples are content re-use, topic-based authoring and content models.

DITA has an elegant way of handling these standard technical writing concepts.

How to learn DITA

Before you start, you need only a very little:

  • An understanding of XML elements and attributes — just know what they are.
  • An idea of the three DITA topic types: concept, task and reference.

Then get a DITA editor, such as XMLMind or XMetal. Suchi usees and recommends XMLMind. You can download a free edition for personal use.

From that point on, the editor helps you to learn the quirks of DITA. Suchi gave us a quick demo of XMLMind, showing us how the editor enforces the DITA rules while you are writing your content.

At this point, you don’t need to know about the complex features of DITA like specialisation, customisation, inheritance, etc. You also don’t need to know about the DITA “topic” topic.

You also don’t need to know about XML rules, validation and well-formedness. The editor will take care of that. You can learn about it later, once you’ve got through the beginner stage.

Because DITA tags are semantic, it’s easy to guess what each element means judging by its name.

Start with a good example. Download and analyse some sample topics. Suchi gave us a link to the DITA OT user guide as a good set of sample topics.

She also recommends this tutorial: DITA for Solo Writers, the Lone-DITA guide.

The real wolves of DITA

DITA is not a wolf, says Suchi. 🙂 On the other hand, the DITA OpenToolkit is horrible. Don’t use it!

Another wolf is ourselves. If you start with a closed mind, it’s hard to learn what DITA offers.

Going further

Once you’ve done some editing and created some content, you can start looking at publishing your DITA content. Here’s where you would install the DITA OpenToolkit, but don’t use it. Instead, install one of the other tools that use the toolkit:

  • WinANT
  • XMLMind DITA Converter
  • Other publishing tools you already own

My conclusion

Thank you to Suchi for a calm, reassuring introduction to DITA. Suchi had the audience in the palm of her hand. Her speaking style is relaxed and charming. She told us about a one-day DITA workshop called “DITA in a Day”, that she has created. It sounds well worth attending!

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.

%d bloggers like this: