REST API documentation embedded in the application

Our development team has built a tool that documents an application’s REST APIs within the application itself. What’s more, you can test the REST resources and methods too. All from the application’s user interface. Now, that’s embedded help for nerds. I’m writing this post because I think many technical writers and developers will be interested in this solution. It may trigger ideas about adding something similar to other applications too.

The tool is called the REST API Browser, and it is implemented as a plugin. At the moment, it is available only within the Atlassian Plugin SDK. In the future, you may be able to download the REST API Browser as a separate plugin and install it into any Atlassian application.

So, what does the REST API Browser do, what is the Atlassian Plugin SDK, and how can you get the REST API Browser to work within an Atlassian application?

Overview of the REST API Browser

This is what the REST API Browser looks like, when running inside an application called JIRA:

The /user/search REST resource in JIRA

JIRA is an issue tracker developed by Atlassian. The above screenshot shows one of the JIRA administration screens, part of the application’s user interface. I’m running JIRA on my local machine, in plugin development mode. The REST API Browser is available as one of the options on the application’s administration screens. It’s as simple as that.

In the screenshot, you can see the resources in the JIRA REST API, starting at the /user/search resource. For each resource, the REST API Browser shows the methods (GET, POST, PUT) and the parameters available.

You can even do real-time testing of the APIs, by submitting a request and seeing the response. In the screenshot below, I have run a GET request using the /user/search resource, asking for details of username “admin”. You can see:

• A form, prompting you for the parameters relevant to the resource and method. In this case, the only parameter is the username.
• The request, as formulated by the REST API Browser.
• The response headers.
• The JSON in the response body.

A REST request and response

The application’s REST APIs at your fingertips!

Which REST APIs does the Browser show?

The REST API Browser displays all the REST and JSON-RPC APIs available in the running installation of the application. That means all the remote APIs that are part of the application’s default installation (JIRA, in this case) as well as any additional REST APIs provided by a plugin.

So, if you install a plugin into JIRA, and that plugin exposes a REST API, the resources will show up in the REST API Browser too. Magic.

Introduction to Atlassian Plugin SDK

The Atlassian Plugin SDK is a tool for developers who want to create a plugin (add-on) for an Atlassian application. For example, you may want to add a new option to the Confluence page menu, showing all authors who have ever updated the current page. Or you may want to add a new option in JIRA that points to your organization’s intranet site.

But the SDK is useful even for people who don’t want to build a plugin. You can use the SDK to download and run an Atlassian application on your own machine, in plugin developer mode. One of the features that you get is the REST API Browser.

How can you get hold of such sweetness?

Here’s a quick start guide. First, install the SDK and use it to download and run your application:

1. Follow the guide to installing the Atlassian Plugin SDK. Do just steps 1, 2 and 3. You can skip the last step, which sets up an IDE (Eclipse, IDEA or NetBeans), if you do not need a development environment.
2. Create a directory in your file system to store the application executables. Let’s assume you want to run the REST API Browser in JIRA. Then, for example, you could create a directory called myjira.
3. Open a command window.
4. Go to the new directory that you just created, myjira.
5. Run atlas-run-standalone --product APPLICATION. For example, atlas-run-standalone --product jira.
   Note: There are two dashes in front of the word product.

After following the above steps, you will have the application running on your computer. When all the downloads and installation are complete (which may take a while), you will see a message in your command window that includes the URL for the local installation of the application.

For JIRA, the message will look something like this:

[INFO] jira started successfully in 174s at http://localhost:2990/jira
[INFO] Type CTRL-D to shutdown gracefully
[INFO] Type CTRL-C to exit

Now you can access the application in your browser and use the REST API Browser from the application user interface:

1. Go to your web browser and enter the URL given for your application. For example, http://localhost:2990/jira.
2. Enter the username and password: admin / admin.
3. Go to the application’s administration screen. For example, in JIRA: Click Administration at top right of the screen.
4. Click REST API Browser on the administration screen.
5. Choose an API from the dropdown list at the top left of the screen.
6. Choose a resource from the list on the left of the screen.
7. See the methods (GET, POST, PUT, etc) and the parameters available for that resource.
8. To test the resource, enter the parameter values as prompted then click Execute.

The documentation has the details of running the REST API Browser in the SDK, and of viewing and testing the resources.

Getting technical: How the REST API Browser works

The source code is available on Bitbucket, as part of the Atlassian Developer Toolbox. The developer’s guide describes how to ensure that a REST API is included in the Remote API Browser. That document also gives a summary of how the browser is put together.

Pretty neat, huh

From a plugin developer’s point of view, the REST API Browser is very useful. From a technical writer’s point of view, I think it’s pretty revolutionary. Has anyone seen other examples of embedded REST API documentation?

Kudos to Rich Manalang and the Atlassian developer relations team for developing this shiny tool. Here is the blog post in which Rich announced it: Introducing the REST API Browser and the Atlassian Developer Toolbox.

WritersUA 2011 Monday – Hotrodding your online help

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Hotrod My Help” presented by Leah Guren. If you find any inaccuracies, they’ll be mine.

Leah’s presentation style is both informal and professional. She started out by introducing herself as “this deranged woman”. She then became more serious quite quickly. Her talk was about design of online help systems. She used the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Introducing the topic

Leah’s talk was entirely tool agnostic, and described techniques that we can apply to our documents with very little effort.

Nevertheless, Leah pointed out, this stuff matters for a number of reasons:

• Design should match the subject matter.
• Better design improves usability.
• We’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.
• When people see help with a sloppy design, they’re less likely to trust the information.
• Design should support the meaning of the content.
• It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah also pointed out that if your readers are noticing the design, then you have made a mistake. (As a side note, I tweeted this point and received an interesting reply from Bill Kerschbaum.)

The design concepts

Leah introduced us to some design concepts, the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to the acronym PARCH:

• Proximity – When elements are close together, we recognise that they are related.
• Alignment – Choose where you position elements on the screen, to develop a meaningful design.
• Repetition – Repeated visual patterns help people to access and remember the information efficiently.
• Contrast
• Hierarchies and dependencies

Proximity

One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment

Use alignment for a less sloppy design.

Repetition

Consider things like colours, icons, placement.  Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast

We need contrast so that people can see the differences in meaning between different elements on the page. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy

This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts and techniques

• White space – Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.
• Plumb lines – Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.
• Indents and text wrap – Indents help the concept of contrast. Good examples are bulleted lists.
• Paragraphs – Leah recommends the following design techniques for paragraphs, to enhance readability:
  • Flush left, ragged right.
  • Single line spacing.
  • White space between paragraphs.
• Chunking – Use white space intelligently, to show the logical visual chunks of information.
• Nesting – Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting. The rule in technical communication (a tacit contract with the user) is this: if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts

After introducing all the theory, Leah moved on to examples of web page makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

These are some of the mistakes she fixed up:

• Messy text.
• Dashboard that was not designed to be meaningful.
• Screenshots taken without care and without tidying up afterwards.
• Sloppy text wrap, that probably happened when pasting content from elsewhere.
• Inconsistency in capitalisation, punctuation, and so on.
• Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
• No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
• Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
• Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
• Use of blue (usually used to denote hyperlinks) as an emphasis or point colour.
• Too many layers of hierarchy (too much nesting) in a table of contents.
• Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
• Empty topics.

Help authoring tools

If the problem we’re addressing lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

Hotrod My Help
=============
Leah Guren (Cow TC) 

http://www.cowtc.com/

Leah started out by introducing herself as “this deranged woman”. Herpresentation style is informal and easy. She then got more serious quite quickly. She does many presentations about tehcnical communication. Today she will talk a lot about deisng. Use the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Everything she will talk about is tool agnostic. These are techniques that you can apply to your documents with very little effort.

This stuff matters because the design should match the sujbect matter. Better design improves usability. we’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.

When people see help with a sloppy design, they’re less likely to trust the information.

If your readers are noticing the design, then you have made a mistake.

Good design follows a series of rules.
Design should support the meaning of the content.
It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah introduced us to some design concepts – the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to a new acronym: PARCH:
* Proximity – When things are close together, we recognise that they are related.
* Alignment – Choose intential places to position elements on the screen, to develop a meaningful design.
* Repetition — Repeated visual patterns help people to access and remember the information efficiently.
* Contrast
* Hierarchies and dependencies

Proximity:
==========
One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment
=========
Less sloppy design.

Repetition
==========
Consider things like colours, icons, placement.

Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast
========
We need contrast so that people can see the differences. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy
===========
This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts:
==============
* White space — Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.

* Plumb lines — Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.

* Indents and text wrap — Indents help the concept of contrast. Good examples are bulleted lists.

* Paragraphs — Leah recommends the following design techniques for paragraphs, to enhance readability:
** Flush left, ragged right.
** Single line spacing.
** White space between paragraphs.

* Chunking — Use white space intelligently, show that we’re showing logical visual chunks of information.

* Nesting — Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting, which all of us do. The rule in technical communication (a tacit contract with the user): if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts
========

With the theory out of the way, Leah moved on to examples of makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

Some of the mistakes she fixed up were:
* Messy text.
* Dashboard that was not designed to be meaningful.
* Screenshots taken without care and without tidying up afterwards.
* Sloppy text wrap, that probably happened when pasting content from elsewhere.
* Inconsistency in capitalisation, punctuation, and so on.
* Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
* No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
* Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
* Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
* Use of blue (link colour) as a highlight colour.
* Too many layers of hierarchy (too much nesting) in a table of contents.
* Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
* Empty topics.

Help authoring tools
====================

If the problem lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions
==============

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

AODC Day 3: Help Authoring Tool Comparison

Two weeks ago I attended AODC 2010, the Australasian Online Documentation and Content conference. We were in Darwin, in Australia’s “Top End”. Over the last couple of weeks, I’ve been posting my summaries of the conference sessions, derived from my notes taken during the presentations. All the credit goes to the presenter. Any mistakes or omissions are my own.

Matthew Ellison presented a number of excellent sessions at this conference. His Friday session was called “Help Authoring Tool Comparison”. He discussed what a help authoring tool (HAT) can do for us as technical writers, then did a detailed comparison of a few popular tools.

What a HAT can do for you

HATs hide the complexity and allow you to concentrate on the content. You don’t need to worry about coding and scripting, conditional tags and other mechanics under the hood.

HATs produce some very nice output, such as browser-based help (WebHelp), PDF and many other types. On the whole, HATs produce the tri-pane output format of online help. If that’s what you need, they make it very easy to do.

They provide help-specific features such as context sensitivity, indexing, dropdowns and related topics.

You can also use HATs for single sourcing.

In summary, HATs cater to our specific needs as technical writers.

Things that may count against a HAT

HATs tend to be proprietary and non-standard. For example, a HAT that supports DITA may not use compliant DITA. This may mean you’d find it difficult to migrate to a different tool. It’s a trade-off between the ease of use and the loss of flexibility.

Compared to a full CMS with XML management, HATs offer limited facilities for content re-use and content management.

Examples of HATs

Matthew emphasised that all the HATs he discussed are excellent tools. His presentation covered the following tools, which are the most popular of the HATs available:

• Adobe RoboHelp (also TCS2, which contains a slightly different version of RoboHelp that offers better integration with FrameMaker)
• Author-it
• ComponentOne Doc-To-Help
• EC Software Help & Manual – a really nice tool.
• MadCap Flare
• WebWorks ePublisher – This tool has been around a long time. It’s not an authoring tool, but rather converts content from one format to another.

Matthew gave us a list of the features that almost all HATs have in common. Then he discussed some criteria for selecting a HAT, examining a number of tools and analysing the strengths and weaknesses of each tool. He covered the following aspects of each tool:

• A short description of the tool
• Workflow
• UI and usability
• Key strengths
• Key weaknesses
• The tool’s own help

I didn’t have time to take notes on everything covered in the presentation. Here follow the notes that I did take.

Adobe RoboHelp

RoboHelp stores its content as XHTML. You work on topics, basically one topic per file. RoboHelp publishes to a number of different formats. The output to AIR Help and WebHelp are very good indeed.

I found this point interesting: If you want a printed document, Adobe recommends that you write your documents in Microsoft Word and link them to RoboHelp as the publishing engine. When printing, print the Word document. For other output formats, publish via Robohelp. You can print directly from RoboHelp, but the output is not great.

If you have TCS2 RoboHelp, you can link FrameMaker documents in the same way as Word documents. FrameMaker gives you a much richer print capability.

The RoboHelp UI and usability are good. RoboHelp goes to some pains to retain a Word-like UI (pre-2007 Word). The UI for linking and importing is not so good.

Other notes:

• You cannot share resources (stylesheets, icons, snippets) across multiple projects.
• The download file is very large.
• RoboHelp’s own help is not all that great, chiefly because it contain features that you cannot create from RoboHelp itself. The information is also not very well structured.

Author-it

Author-it stores its content in a single library in the database. You can connect to your own database: SQL Server or JET / SQL Server Express (free). On the minus side, Author-it stores the content in a proprietary rather than a standard storage format.

Author-it offers a very powerful capability for content re-use.

You can publish to a number of different output formats. All print outputs are generated via Microsoft Word. This can be seen as clumsy and a problematic dependency. It does produce excellent Word documents.

The UI is very complex, requiring a steep learning curve. It has a very modern look and feel.

Author-it has a number of capabilities, probably the longest list of all the HATs. Some of the add-ons are very powerful, such as authoring memory which tracks duplicate content. It has good support for localisation. Another feature offers web-based authoring too.

The help system is pretty good, and is recognisably generated from Author-it itself. It’s also mirrored on the web, so you can find the information via Google too.

ComponentOne Doc-To-Help

This is the original HAT. Originally the idea was to work in Word and convert to Doc-To-Help. But now you can also choose to edit in XHTML using the Doc-To-Help WYSIWYG editor.

To create styles, you actually create Word .dot files. At first use, this seems a bit odd. Doc-To-Help generates CSS from the .dot files.

It also has a database where you can store metadata.

Doc-To-Help offers a number of output formats.

The UI has improved over the years. It’s a professional-looking, ribbon-based UI.

Doc-To-Help has some cool features, such as the ability to create relationships between topics, similar to the way Author-it does.

It also integrates with Microsoft Sandcastle for documenting class libraries based on comments in the code.

Doc-To-Help’s own help is good.

EC Software Help & Manual

Help & Manual has a very nice WYSIWYG editor, where you edit in XML. It has its own DTD.

It imports content nicely. If importing from Word, save to RTF first. There’s no FrameMaker or DITA support.

The UI is very nice. Of all the tools, it’s the easiest and most comfortable to use (even though ribbon-based). The UI is driven by the table of contents. It offers a simple user experience, yet there are some good advanced features which you can find if you look for them.

One great advanced feature is the skins that you can use to achieve consistency across projects. You can also share resources, such as style sheets, across projects.

MadCap Flare

All editing in Flare is in XHTML, using the WYSIWYG editor.

Flare does a very good job of producing print and help output formats. There’s also a WebHelp Mobile output

You can input DITA, as well as other formats.

The UI is fairly easy to learn, but has some stumbling blocks. You do need to understand CSS to get the most out of it.

Flare has the most excellent help system Matthew has ever seen.

Offering your users the ability to collaborate on your help pages: As an add-on, you can buy the collaboration module so that users can comment on the topics and read each others’ comments.

WebWorks ePublisher

Note that ePublisher is not an authoring tool. There is no editor. You use it to publish content from Word, FrameMaker or DITA to a large number of output formats.

ePublisher offers a large number of mappings that you use map from your input styles to your output styles.

The UI and usability is slightly confusing. There are actually two products involved. ePublisher Express is very simple. That’s the one you use to publish the output. ePublisher Pro is where you create the mappings, and the UI is more complex.

The WebHelp output is not very pretty or professional. The TOC (table of contents) output is fixed by the TOC of the source document.

ePublisher’s own web-based help, published on a wiki, is just bad. On the other hand, the local help that you get when you install the product is much better.

Final comments from Matthew

Always test drive with real data before buying a tool. All the products discussed in this presentation are great tools!

My conclusion

This was a very thorough and in-depth analysis of the features, strengths and weaknesses of the most popular HATs around. I didn’t have time to take enough notes to do it justice. In particular, Matthew showed a useful workflow diagram for each tool. Thank you Matthew for another great presentation.

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?

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 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:

• QuickOffice
• Timewerks

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

iPhone

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.

Syncing

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:

<resources>

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

<string name="retry">RETRY</string>

</resources>

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.