In the past, user assistance was typically a version of a printed deliverable that was repurposed for online use into WinHelp, HTML Help, and WebHelp formats, among others. Today’s web-enabled world has changed the expectations around user assistance.

Today’s intuitive applications require a help model that is unencumbered by complicated navigation, unnecessary information, and platform inflexibility. That help should be simple, flexible, and designed for the needs of the user. As a developer of online user assistance, the focus is how to move from being a content builder to a content architect.

Many technical communicators view online help as simply being a dump of a user manual (with a few tweaks) into a different format. We believe this is the wrong approach. Online help should:

• Contain only the information that users absolutely need (tastes great, less filling)
• Adopt a flexible format that meets a diverse set of needs
• Be easy to navigate and search
• Avoid distracting the user from the task at hand
• Not be aligned to specific tools

We spend so much time worrying about the usability of the application that we gloss over the usability of the user assistance that’s included with the application. It doesn’t have to be that way. By looking at what user assistance currently is and what it could be, Aaron Davis and Scott Nesbitt will:

• Outline the shortcomings of the universally accepted online help model
• Explain why simple doesn’t mean incomplete
• Explore how to give users the information they want, in the way they need it
• Discuss how to break down the walls surrounding user assistance
• Look at new technology—like RSS, wikis, and social networking—to enrich the overall user experience

When your organization transitions from “traditional” publication methodologies to XML and DITA, it’s a good time to consider the tool that your authors use to create content. There are two competing schools of thought on XML authoring: use a more familiar WYSIWYG tool (such as Adobe FrameMaker) or use a newer tool that is much closer to XML (such as XMetaL from Just Systems). Both FrameMaker and XMetaL provide some level of integration with DITA, which makes them both viable candidates. This presentation uses live demonstrations to illustrate the advantages and disadvantages of both FrameMaker and XMetaL when working with DITA.  The presentation shows the highlights of both tools, the authoring experience, generating output, conditional processing, working with conrefs, map files, and specialization. The presentation concludes with a series of guidelines to help you assess your situation and which tool might be best for you.

Documenting Application Programming Interfaces (APIs) and Software Development Kits (SDKs) is a challenging but rewarding niche in technical communication. This session discusses what these products do, who uses them, moving into this area, benefits / drawbacks to working on these products, issues unique to these products, and commonly used help authoring tools. As the demand is often greater than the supply of writers, you can get higher pay than for other types of writing. You often get greater flexibility in telecommuting / working remotely in this area. Sample source code and the documentation produced from them will be shown.

Attendees will learn about the skills needed to break into this area of technical writing, and be introduced to some of the tools commonly used to document APIs and SDKs.

The following topics will be discussed:

• Introduce APIs / SDKs, describe them and their function. Demonstrate several examples of APIs / SDKs and point out the similarities of information provided and format among them.
• Typical documentation deliverables for both types of products.
• The ideal information for SDKs.
• The typical reference information for APIs.
• Common programming concepts that writers need to be familiar with for this type of writing.
• The benefits and drawbacks to doing this type of writing.
• The knowledge / personality traits that work well in this area.
• Sources of training to prepare you for this area.
• Logistical issues faced by writers: how you get your information, tools you can use, common formats for online help, platform issues, build and deployment issues, etc.
• Some common tools used to generate the documentation from the source code, “a single source of truth” will be demonstrated, showing the source code and the documentation generated from it.
• Other advanced, powerful shareware tools tthat are very useful for documenting these types of products, such as tools to compare the contents of directories / files, search and replace tools, and advanced text editors.
• Factors to consider in determining which help format to use.
• Determining if context-sensitive help is useful and tips for making it easier to track your context-sensitive IDs / numbers.

You think you might need a new Help Authoring Tool (HAT), but there are a lot to choose from. You’ve read blogs and press releases and articles and forums and email lists, and you’ve noticed that a lot of people have a favorite HAT.

However, you need to focus on your needs when choosing the HAT that will work best for you. It won’t matter how many other people use a HAT if it doesn’t produce the output you need or if it won’t run on the platforms your customers use.

During this session, you’ll learn about four features that matter when choosing a HAT:

• Outputs—We will start with a really quick discussion of the outputs that are available from all HATs, and then move on to the important questions. What outputs can the HAT produce? Can you customize them to match your company branding? What platforms and browsers can be used?
• Development environments—The lines are blurring between traditional HATs, where all authoring takes place in the HAT, and publishing HATs, which reference the source documents. Which HATs have combined authoring and publishing? Which have their own authoring environments? Which let you mix-and-match? Will you want to leverage your existing knowledge or learn a new editor?
• Importing legacy content—While you will have some new projects, you will also likely have existing content that needs to be imported. What types of content can be imported? What issues should you watch for?
• Reusing content—In today’s world, reuse is big. (And content is king.) Some HATs let you reuse content within projects, while others let you reuse content across projects. Some let you combine deliverables within one project through the use of build tags or other types of markers, letting you publish both a User’s Guide and a Training Guide. Some HATs let you take advantage of variables, snippets, widgets, topics, and more, or a combination of all. What types of reuse should you evaluate? Can you reuse layouts, templates, and browse sequences?

  By the end of the session, you will have put together a checklist of features that matter to you.

  
  

  Getting Up-to-Speed on Eclipse User Assistance

  Speaker: Lee Anne Kowalski
  Time: 3:30 PM - 5:00 PM   Date: October 30
  Track: User Assistance DocTrain East 2008
  Experience level: Intermediate
  Room: Salon I - J
  

  Has your development team just announced “We’re moving our applications to Eclipse!”? Are you wondering how on earth you’ll create the online help for these applications? Or are you asking “what the heck is this Eclipse thing?” If so, this session is for you! In this session, we’ll cover what Eclipse is, what user assistance and online help mechanisms it provides, and what you need to do to deliver content effectively in an Eclipse-based application.

  In this session, attendees will learn:

  • What Eclipse is and what their developers mean when they say “we’re doing an Eclipse product”
  • What the different Eclipse user assistance pieces are and how they are used by end users of an Eclipse-based application
  • Practical approaches for authoring their content and delivering it as Eclipse UA

  After this session, attendees can return to their jobs with a set of practical methods, tips, and tricks for producing content for delivery in an Eclipse-based application.