Eclipse: Don't Get Left In The Dark

by Fei Min Lorente, Volunteer Manager

This article originally appeared in the STC Publication, Intercom, and is reprinted here with permission.

If you are a technical communicator in the software industry, you may have already heard about Eclipse. If you haven't, you probably will.

Eclipse is an open-source, integrated development environment (IDE) that is rapidly growing in popularity among educational institutions, software companies of all sizes, and their vendors and clients. With software comes help menus, help buttons, and ideally, integrated help. The demand for Eclipse-based integrated help (or user assistance) is so great that standard documentation tools-such as Mif2Go, XMLSpy®, and ePublisher-now produce Eclipse help.

What is Eclipse?

Eclipse defines itself as "an open source community whose projects are focused on building an open development platform comprised of extensible frameworks, tools and runtimes for building, deploying and managing software across the lifecycle." In other words, Eclipse is a single, integrated development environment where software developers can write, compile, run, and debug code; manage the source, manage projects, send and receive email messages; perform scheduling; revise task lists; and more. Eclipse users (be they software developers or otherwise) can also access and use integrated user assistance.

A key feature of Eclipse is that it is extensible, which means that after you install Eclipse, you can customize it to meet your needs using plug-ins. Plug-ins and customizations also require integrated documentation, which is added as an extension to the primary documentation.

Another key feature is that Eclipse is open source. Not only is Eclipse free, but when a company adds value to that free platform, they can also sell their resulting enhanced product without developing the entire application from scratch. As more companies produce Eclipse-based products, technical writers will need to write and deliver Eclipse-based user assistance.

Open source also means that the finest minds in the world can contribute to this product; it is not limited to a single company. Although it is free to users, many of the developers are paid employees of Borland, HP, IBM, SAP, and Wind River, just to name a few. With an annual release train, the Eclipse platform is under active development and is reliable enough to meet the rigors of commercial applications.

Who uses Eclipse?

A December 2007 study conducted by BZ Research shows Eclipse is used 62.7 percent of the time compared with its closest competitor, Sun NetBeans, at 24.4 percent (as reported by Alan Zeichick in his weblog. The Eclipse Community survey conducted in October 2007 describes the kinds of organizations that are using Eclipse in terms of size and the types of projects. While I first heard about Eclipse five years ago, I now find that, in a room of technical writers, at least one person will have heard of Eclipse, if not used it.

Where do technical communicators fit in?

This all sounds wonderful for software developers, but is Eclipse relevant to technical communicators? I think so. Depending on your product, you might choose one of the following modes to run the Eclipse user-assistance code:

• If your product is Eclipse-based, the workbench mode is available; help is integrated with the product. For example, if your company decides to deliver a product on the Eclipse platform, they may ask you to adapt your user-assistance documentation. Customers will expect integrated help, and technical communicators are the ones to provide it. The more popular Eclipse becomes, the more you will encounter this situation.
• If your product is not Eclipse-based, you might choose the standalone mode. A smaller version of Eclipse is shipped and installed with your software product and called up from your product's Help menu.
• If you want to deliver the help content over the Web, you would choose the infocenter mode. For example, if your company's product is not Eclipse-based, but you need a tool to display your documentation electronically, you might consider using Eclipse user assistance, thereby avoiding the cost of purchasing and writing a help system. Standalone and infocenter modes only provide the Help Contents user assistance. Once you know all the ways you can provide information to your users, you can decide if and how Eclipse is useful to you.

Technical Communicator Decisions

When providing Eclipse user assistance as one of your deliverables, here are some items to consider:

• Decide which Eclipse user-assistance format to use for various parts of your documentation: help files, welcome pages, or interactive tutorials.
• Determine how to generate the file types that Eclipse needs for its formats and which ones to use (such as XHTML or HTML for help files).
• Welcome pages-ideal for introductory and auxiliary information, such as "What's New" and technical-support contacts.
• Employ topic-based writing (because content is typically displayed in at least three different ways: table of contents, context-sensitive help, and user-search actions).
• Find tools that produce Eclipse user-assistance files or write a script that converts your table-of-contents files to the required XML formats.

It is likely that your responsibilities with respect to Eclipse will be determined by your organization. Some technical communicators will simply provide HTML files to software developers, and the developers will incorporate them into the Eclipse user assistance. Other technical communicators will need to develop Eclipse user assistance themselves. In this case, they have to be comfortable with XML, plug-ins, build configurations, and even Java. All technical communicators who deliver their information via Eclipse need to know how that information will appear to users, and what types of Eclipse user-assistance formats exist so that they can make wise choices about the best way to write and present the material.

User Assistance Formats

User assistance formats support the following types of deliverables:

• Topic-based documentation for help-organized with a table of contents, this provides the bulk of your supporting content. (To distinguish this type of content from the general use of the word "help", I call it "Help Contents" in this article.)
• PDF files-for customers who still like to print their documentation in book form.
• Welcome pages-ideal for introductory and auxiliary information, such as "What's New" and technical-support contacts.
• Interactive tutorials-intended to be brief and simple (in Eclipse they are called "cheat sheets").

Eclipse User Assistance in Action (Eclipse 3.4 Ganymede)

Eclipse 3.4, known as Ganymede, was released on 25 June 2008. Eclipse has regular releases every year, usually in June. Beta versions are released prior to the final release so that software departments have time to preview upcoming features and adjust to the changes.

The following examples are based on the SignaKlara® Development Tools IDE, running on Ganymede:

Help Contents

The bulk of your documentation is displayed by choosing Help Contents from the Help menu. The documentation set then appears in a separate window (see Figure 1), with a table of contents (TOC) in the left pane and the contents in the right pane.

The TOC is composed of one or more XML files with links to individual pages or to embedded anchors. The pages can be written in HTML or XHTML. Additionally, the TOC can link to PDF files.

Help Authoring Tools (HATs) that support Eclipse Help Contents can create the XML TOC files. Some other help formats that are not exactly the same as Eclipse, such as JavaHelp, can be converted with a simple search and replace, which could be automated by a script. The TOC file's XML can also be modified manually in a text editor.

Even when delivering your organization's customized product, you will probably choose to keep the Workbench User Guide, which is provided by the Eclipse organization. It contains all the basic information about using the IDE that your customers will need, and most companies usually have insufficient resources to rewrite it.

Navigation aids include bookmarks, breadcrumbs (a single line of text showing a page's location in the site hierarchy, with links to each parent page), and a button that highlights the TOC entry for the page you are viewing, called "Show in Table of Contents." In your HTML topic pages, you can add your own navigation aids, such as a "return to top" button.

To help users find particular information, you can provide a keyword index in the required XML format. Again, HATs that support Eclipse can provide these automatically; otherwise you have to script or handwrite these files. The keyword index is still being refined, however, and currently has a couple of stumbling blocks (remember, this is open source!):

• While there is support for listing "see" and "see also" entries in the keyword index, those entries do not link to the referenced term. For example, for the entry "JRE, see Java Runtime Environment," you cannot click on it and jump to the "Java Runtime Environment" entry.
• The indices for the installed manuals are integrated into one keyword index, and there is no way to identify to which manual the index entry refers. This information might help a user to select an index entry.

Most useful of all, you can search the Help Contents in several different ways, which I discuss in detail below.

Welcome

Before user assistance in Eclipse, we had "release notes." The welcome pages (see Figure 2) are a good place for information like that, as well as basic "getting started" information, and who to contact for technical support.

The icons you see here are selected from a library provided by Eclipse. It is difficult to use your own icons because several different versions of the same icon are required for use in different contexts. The positioning of the icons is also hard to change. You do have control over the mouse-over text, but not over the formatting of it.

Clicking on an icon displays a specific Welcome page (see Figure 3). The icons here are also from Eclipse and you have no control over the look or feel of this page unless you delve into the Eclipse code. However, you can control the text and link the icons to pages in Help Contents. This is one example of how to reuse the Help Contents.

Cheat Sheets

Cheat sheets are interactive tutorials that appear in a side panel or view that allow you to perform the steps while reading the instructions (see Figure 4). As a result, each tutorial is intended to be brief.

Cheat sheets must be written as XML files and are not intended for reuse within the other formats; that is, their content won't appear in searches or context-sensitive help.

The cheat sheet XML structure allows for sub-steps to convey a procedure-within-the-procedure. The XML formatting elements are limited to bold, and sadly, these tags do not work in the sub-steps.

The cheat sheets allow for a help icon where you can link to further information about a particular step. This information can be part of the Help Contents (another example of reuse) and be as long and detailed as necessary.

As for interactivity, each step automatically expands and collapses as users finish with each one. The best feature of all is that you can provide buttons to invoke menu items on the user's behalf. For example, when a user selects "Click to perform," a dialog box appears as though the user had followed the menu choices. This is an example of the concept of "integrated" user assistance.

Searching

You can perform a full-text search from the Help Contents window (Figure 5). If you pre-index the contents, users do not have to wait for the search index to be created when they first perform a search on a newly installed product. You can also limit the scope of the search to a particular collection of documents.

When you select Search from the Help menu, you have the added option of searching the web using a search engine of your choice.

Pressing F1 gives you context-sensitive and dynamic help (only available in workbench help mode), as shown in Figure 6. Eclipse automatically detects which view is active and provides a link to the Eclipse information about that view. You can change or add links to this context help as necessary. At the same time, dynamic help returns search results based on whatever text you have selected in an editor, or based on where your cursor is. For example, as you select different text, the search results automatically change. This is another way in which the Help Contents information is reused.

Conclusion

Eclipse is growing in popularity in the software development community. As more software companies use it, more technical writers will be asked to provide integrated user assistance for products developed for Eclipse. Since the user assistance features are reasonably robust and well-maintained, and the platform is free, you might adopt it as your documentation delivery system in standalone or infocenter mode.

This article provides only an overview; a product that is this powerful and flexible is also complex. To use it successfully, you will need to understand the organization of the document files, the XML structure for various user assistance formats, the available tools, localization, how to customize it, and more. This information is hard to find because no one sells training on Eclipse user assistance, and books and conferences are geared to software developers.

The websites www.eclipse.org and http://help.eclipse.org/ganymede/index.jsp contain official information about Eclipse. In the Eclipse documentation, see especially "User assistance support" in the "Platform Plug-in Developers Guide." The more you know about XML and java programming, the easier these files will be to understand.

Another source for information is the Eclipse Platform Technical Writer discussion list. The technical communicators on the list, all of whom work with Eclipse, can help you work through any problems you encounter, no matter how simple or complex.

Regardless of your reasons for choosing Eclipse user assistance, the technical writing community has to contend with the focus of the Eclipse community on software developers. It's time that we help each other obtain the information we need in order to work in an Eclipse environment.

About Fei Min Lorente

Fei Min Lorente (feimin.lorente@onsemi.com) is a senior member of STC, and a Senior Technical Communicator at the medical division of ON Semiconductor, where she has had the opportunity to learn and implement Eclipse user assistance as a lone writer. Her work experience encompasses technical communication in the database, banking, automated pipeline control, and defense industries. She maintains a fondness for software and considers herself a programming dilettante.