 | Level: Introductory Chris Aniszczyk (zx@us.ibm.com), Software Engineer, IBM
27 Feb 2007 This article introduces the Eclipse User Assistance project and discusses the many ways to deliver quality user assistance for your Eclipse-based applications.
For any piece of software, the ability to short-circuit a user's learning curve is critical to the adoption and success of that piece of software. Thankfully, Eclipse has the User Assistance project (see Resources), which includes tools for Eclipse-based applications to improve the end users' experience. According to the Eclipse User Assistance project Web site, the project's mission "is to provide for assisting users of Eclipse applications in all phases of the usage cycle. It is not a single workbench artifact, but rather a collection artifacts tailored to provide a particular flavor of assistance."
This article explains some of these artifacts through examples and relevant listings of extension points. Our purpose is not to go into depth into each of these artifacts (see Resources), but rather to serve as a gentle introduction to developers wishing to get started in helping their users.
Tour de Eclipse User Assistance
The Eclipse User Assistance project comprises many components, but provides three main tools to assist users:
- Welcome framework
- Cheat sheets
- Help
Welcome framework
Users launching Eclipse are greeted with a welcome screen.
Figure 1. Eclipse welcome
The Eclipse welcome screen provides easy access to tutorials and samples for users. If you want something similar for the users of your application, Eclipse provides the welcome framework. The welcome framework provides the facilities (by way of welcome content) for you to help guide users through tasks like initial setup or provide easy access to online resources. Welcome content can be specified using raw SWT widgets, or more typically, a series of integrated Web pages. To get a good idea of what typical welcome content looks like, we'll use Plug-in Development Environment (PDE) -- using a template -- to create a sample RCP application that provides welcome content.
To take advantage of the PDE template, we need to create a new plug-in project first (File > New > Project... > Plug-in Project). It is important to state that we are creating a Rich Client Application in the new plug-in project wizard. Once this is done and we advance to the next page, we can create a project using a set of templates. In our case, we want to select the RCP application with an intro template.
Figure 2. RCP application with an intro template
After the plug-in project is created, we can launch the application and see that it pops up to a new welcome screen.
Figure 3. RCP application with welcome screen
If we look at dissecting the generated plug-in, we can see that it uses a few extensions (see Table 1). In particular, we're interested in the use of the org.eclipse.ui.intro.config extension point, whereby the application links to the introContent.xml file. This file contains links to XHTML files, which serve as the welcome content. It's that simple to start building welcome content.
Table 1. Relevant welcome framework extension points
| Extension point | Description |
|---|
|
org.eclipse.ui.intro | This is used to associate an introduction screen with a specific product. |
|---|
|
org.eclipse.ui.intro.config
| This is used to create an introductory configuration. Intro configurations are the fundamental building block of Eclipse's welcome framework. |
|---|
|
org.eclipse.ui.intro.configExtension | This is used to extend an existing introduction configuration with more content. It also provides a way to separate content from specific configurations so welcome content is more reusable. |
|---|
Cheat sheets
Cheat sheets can be thought of as an interactive set of instructions to complete a particular task. They provide a way to guide users through a series of steps with the possibility of scripting interactive actions to simplify what a user needs to do. For example, say you have an application that requires a user to create a special type of project (for example, a photo project) to start working with your application. Cheat sheets allow you to launch your new project wizard automatically, instead of having the user do it manually. A good example of this behavior is the Create a Hello World application cheat sheet.
Figure 4. Create a Hello World application cheat sheet
Eclipse provides an easy way to author these cheat sheets through a new editor (since Eclipse V3.3) that can be seen in Figure 5 and accessed easily using File > New > Other... > User Assistance > Cheat Sheet. This is much easier for those who don't want to work directly with the XML format of Eclipse cheat sheet files. On top of this new editor, there's a command composer that allows you to easily link with existing Eclipse commands. This effectively removes the guesswork and error-prone nature of working with commands by hand in Eclipse.
Figure 5. Cheat sheet editor and command composer
The relevant extension points for cheat sheets are listed below.
Table 2. Relevant cheat sheet extension points
Help
If you worked with Eclipse or IBM® products before, you have most likely stumbled along things known as infocenters. Infocenters are part of the Eclipse help system that offers the ability for you to contribute and organize content and allow for users to search that content quickly. The content can be accessed within Eclipse itself (Help > Help Contents...) or via a browser using infocenters as mentioned. Generally, help content is organized into a hierarchy of XML files that link to HTML files. If you already have help content in one of the popular documentation formats like Darwin Information Typing Architecture (DITA) or DocBook, there are transforms available to turn your content into a consumable Eclipse help plug-in.
|
Help content producers
As of Eclipse V3.3, there is a notion of a help content producer (see the org.eclipse.help.contentProducer extension point) that effectively allows other sources of documentation (like DITA or DocBook) to be plugged into the Eclipse help system.
|
|
PDE has an excellent template to get you started with what sample help content should look like. By selecting the Plug-in with sample help content template (see Figure 6), PDE will create an initial project that has an extension of the org.eclipse.help.toc extension point. After the project has been created, simply launch a new runtime workbench and select help (Help > Help Contents...) to see your help contribution in action.
Figure 6. Sample help content template
Remote help is now an option as of Eclipse V3.3. What this means is you are now able to ship help content separately from your actual application. Instead, you can have a server hosting help content and your application pointing to the help server (see Figure 7). This way, when a user requests help, it will be downloaded when needed. As a developer, you have to be careful about this because if your users are working in an offline environment, this could be detrimental as they won't be able to get help. It's a balance of reducing the initial size of your application download vs. the convenience of working totally in an offline environment.
Figure 7. Sample remote help settings
The relevant extension points for Eclipse help are listed below.
Table 3. Relevant cheat sheet extension points
Conclusion
This article introduced the user assistance facilities of Eclipse and entices you, as a developer, to consider using these facilities to benefit your end users. In the end, good -- and integrated -- documentation can go a long way in reducing the learning curve of your users and the Eclipse User Assistance project provides the tools to get you started.
Acknowledgements
The author would like to thank Dejan Glozic, Curtis D'Entremont, Lee Anne Kowalski, and Chris Goldthorpe for their UA expertise in reviewing this article.
Resources Learn
Get products and technologies
Discuss
-
The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this link will launch your default Usenet news reader application and open eclipse.platform.)
-
The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
-
Participate in developerWorks blogs and get involved in the developerWorks community.
About the author | 
| | Chris Aniszczyk is a software engineer at IBM Lotus focusing on OSGi related development. He is an open source enthusiast at heart, and he works on the Gentoo Linux distribution and is a committer on a few Eclipse projects (PDE, ECF, EMFT). He's always available to discuss open source and Eclipse over a frosty beverage. |
Rate this page
| |
