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.

Salon I - J

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.

The best software user assistance is so elegant that users don’t need to look for it. In Doc-To-Help 2008, the embedded dynamic help window and expanded tooltips display relevant information as the user navigates the interface. This session will demonstrate this project and discuss how the interface was planned to include all-around user assistance, how the online Help was structured to work with the interface, and how mappings and other information were managed without the need for custom software development.

This session will also discuss:

• Planning for information layers
• Structuring your help project for embedded dynamic help
• Mapping embedded dynamic help to the interface
• Single-sourcing best practices and methodologies
• Managing the UA in the interface
• How you can duplicate the same sort of user experience yourself

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 - 4:30 PM   Date: October 30
  Track: User Assistance
  Experience level: Intermediate
  

  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.