Category Archives: 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.
- Hierarchies and dependencies
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.
Use alignment for a less sloppy design.
Consider things like colours, icons, placement. Stylistic repetition reinforces the information for the user and gives them more confidence.
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.
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.
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!
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.
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.
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)
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.
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.
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:
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.
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.
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.
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.
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:
This was an awesome window into the world of iPhone and iPad UA development. It sounds like a lot of fun. Thank you Joe.