December 2006 Volume 10, Number 4

New TurnOver Client Boasts Growing Help System

By Mary Schoppmeyer, Senior Technical Writer

If you’ve experimented with our new TurnOver Client software, you likely have experienced our new online Help system. The new Eclipse-based Client was such an advance for TurnOver that our documentation in PDF format seemed passé in comparison. It was time to embrace the future, and just … go online!

As it does many tasks, Eclipse made the job of creating an on-line help system easier. The Eclipse framework includes a help plug-in that takes care of necessary infrastructure – appearance, navigation, searching, book marking. All we had to do was build the content with a help authoring tool and drop it in.

Please join me for a brief guided tour that will show you how to get the most out of our new TurnOver Client online Help system.

Finding Help in the Client

Figure 1: Help menu contents for the Eclipse-based WDSC (left) and TurnOver clients

No matter where you’re running our new Eclipse-based TurnOver software components – be it the standalone TurnOver Client, or IBM’s WDSC IDE, or even in Eclipse itself – our Help system is the same. Likewise with how you access it: use the Help Contents link on your product’s Help menu.

(Be aware that you can also use F1 from just about anywhere – but this method behaves differently in WDSC than in the TurnOver Client, because the two are built over different versions of the Eclipse platform. I’ll say more about that in a minute.)

When you choose Help Contents, the Help browser opens. The Help browser consists of two panes; the left pane contains a set of tabbed views for navigation, and the right pane is the topic viewing area. On entry, the Contents tab is active in the left pane, showing all available help “books,” including one named TurnOver. When you click the TurnOver “book,” you’ll see TurnOver’s Welcome page:

Figure 2: Note that only the information associated with the TurnOver components that you actually have installed appears in the Table of Contents.

TurnOver’s expandable, tree-style help structure is simple and logical, and reflects the product structure. Each TurnOver software component contributes one chapter to the TurnOver book for every subsystem it provides. For example, the Developer component contributes two subsystems – Development, and Worklists. It follows, therefore, that if you have the Development component installed, you’ll see in the TurnOver book a chapter for Development and a chapter for Worklists.

Each chapter contains four categories, or sections, of information about its subsystem: Introduction, Concepts, Procedures, and Reference. Introductory information provides a high-level description of the component and how it fits into the big TurnOver picture. Conceptual information describes the building blocks or features that the component uses to do its TurnOver work. Procedures explain how to use the software to make the component building blocks do their job. Reference information consists of definitions, field descriptions, or other additional background content to complement your understanding of the TurnOver component.

Each document in a section represents an individual topic, and might have other documents associated with it.

Using the TurnOver Help System

TurnOver’s Help structure makes it easy to retrieve information if you know where the information should come from. But what if you aren’t sure? Then search – of course! A fully functional search engine for online Help is delivered on a Search bar at the top of the Help browser.

Figure 3: Fully functional search engine for online Help

The search engine accepts Boolean searches, wildcards, and quoted phrases (things we’ve all come to expect from most search engines anywhere) and returns a list of topics in the left pane. For practice, I do recommend opening the Help browser and searching for the phrase “searching online help” to read detailed information about how to use Booleans, wildcards, and quoted phrases.

A second facet to the Help browser’s search feature is the ability to limit the search scope. Because the Help system indexes the content the first time you search during any given session, it is useful to limit the scope when you are looking for product-specific information. Limiting the scope can save you time initially, by excluding unnecessary topics during the indexing process. It also saves time during subsequent searches performed during the same session by reducing the amount of unrelated content you need to sift through once results are delivered.

Figure 4: Limiting search scope

To limit the search scope, you create named information sets called search lists that include only the books you want to search. You can group all TurnOver-related topics in one list, and Workbench-related topics in another, for example. To create a search list, click the Search scope link on the Search bar. Experiment with it - the user interface is pretty self-explanatory. (For more practice, try creating a search list named “Workbench” that contains only topics from the Workbench User Guide. Then search it for the string “searching online help” and see what results you get.)

Behavioral Differences between the TurnOver Client and WDSC

As I mentioned earlier, online help content is the same regardless of where you view it. However, because the standalone TurnOver Client is built over Eclipse 3.1 and WDSC over Eclipse 3.0, the two do behave slightly differently if you use F1 to open the Help browser. This is because Eclipse 3.1 introduced a feature called Dynamic Help, which launches a search of all available topics, using as criteria information gleaned from the view you were focused on when you pressed F1.

In previous Eclipse releases, F1 presented something they call an “infopop” that contains three links into the Workbench help. Nice - but not very helpful if what you want is TurnOver information, and certainly not context sensitive in the way today’s online Help systems have conditioned us to expect. The new Dynamic Help feature presents a far more context-sensitive-like result that includes not only the standard Workbench links, but also a list of topics with matching words or phrases from all contributed content within the search scope. The outcome is a more direct route into context appropriate help using the ubiquitous F1, which the whole world has come to regard as THE key for Help. (Just a little something for WDSC users to look forward to in the next release.)

It’s YOUR Help System

It’s important that ANY Help system be … well, helpful. We add improvements to the TurnOver Help system on a quarterly basis, so it continues to evolve. However, we’re aware that one of the best ways to make it the most useful system for you, our customer, is to give you a way to tell us when it doesn’t meet your needs.

Beginning with our December TurnOver CD, you’ll be able to send feedback about an online Help topic in the Client Help system directly to a documentation specialist here at SoftLanding.

The footer of each online Help topic will contain a link inviting you to send us feedback. Clicking the link will construct an email in which you can include your comments and suggestions.

When you send the email, it will go directly to an ExpressDesk monitored mailbox (see Sandy King’s article, in this issue). Your email will become a Help Information Request in our system, and we’ll promptly review your suggestion and consider it for inclusion in the next round of updates. (We might contact you for clarification.)

Still Paper-starved?

The search features alone are a great reason to discover the online Help for your TurnOver plug-ins. You get your very own copy, and you can bookmark it to your heart’s content. In addition, there’s the convenience of having MUCH more TurnOver information available to you in one place, without having to jump from book to book or dig up the quarterly CD from your co-worker’s desk so you can search the PDF collection.

If once you’ve tried it you’re still yearning for paper, you could try printing each Help topic. One at a time. Slowly. Just to savor the experience.

Back to Table of Contents

WHAT'S NEW