getting up to speed on eclipse user assistance

© 2008 by Dr. Lee Anne Kowalski. Made available under the Eclipse Public License, v1.0

Getting Up To Speed on Eclipse™ User Assistance

Dr. Lee Anne KowalskiTelleltis [email protected]


About me 16 years experience as a

technical writer and information architect

Working with Eclipse since V2.0 (2002)

Project lead for development team enhancing standalone Eclipse help system/infocenter for use within IBM (2003 – 2007)


What is this talk about?

Boss says: “We’re going to do an Eclipse version of our product. When can you give me a plan for delivering the online help?”


What pops into your mind How can I be successful in this? Why are we doing this? What output form is “Eclipse help”? Can I reuse my source files? Can I

reuse my CHM files? Can I use my same authoring tools? If

not, what can I use? Who can I ask? Should I start looking for a new job?


First time out

Seek simplicity!


Eclipse is…

An open-source integrated development environment (IDE)

A community

An open platform for buildingAn open platform for buildingany type of applicationany type of application


Why Eclipse is attractive to decision makers?

Minimizes costs (short & long term) “Open source”

Free/low cost Unfettered (simple licensing)

Extensible Vibrant, growing community

Maximizes opportunities Many platforms/devices, native look &

feel Modularity (plug-ins/bundles) Ecosystem driven


The UA features (live demo)

Eclipse 3.4 Software Developers Kit (SDK) (Eclipse “Workbench”)

Help Contents tri-pane window

Contextual (embedded/F1) help

Welcome pages Cheat sheets Eclipse SDK displaying the embedded help

view


Getting and starting the Eclipse Workbench (Windows)

1. Download package from www.eclipse.org

“Classic” package good to start with

2. Unzip using zip tool (issues with XP native extraction)

3. Double-click eclipse.exe in the eclipse directory

http://www.eclipse.org/


The Workbench

Eclipse 3.4 (“Ganymede”)


Make conscious choices

Base UA choices on your “Going to Eclipse”

scenario Target audience

expectations and requirements


Typical “going to Eclipse” scenarios

Scenarios ExamplesExtend the Eclipse Workbench (IDE) MyEclipse Enterprise

WorkbenchCreate Workbench plug-ins <oXygen/>® XML AuthorCreate desktop app Actuate BIRT Report

DesignerProject owner/member Data Tools Project (Sybase)


Observed pairingsScenarios Exploited UA mechanismsExtend the Eclipse Workbench (IDE)

Help Contents (topics, ToC, index)Contextual helpTypically: Welcome pagesOptionally: Cheat sheets

Create Workbench plug-ins

Help ContentsContextual help (audience dependent)Optionally: Cheat sheets

Create desktop app

Help ContentsOptionally: Contextual help, cheat sheets, Welcome pages

Project owner/member

Depends on the nature of the project


What you’ll create

“doc” plug-ins Loosely = a chm Packaged in a “plug-in

archive file” (.jar file) Unjar’d directories

can work (e.g., when testing)


About Eclipse plug-ins Eclipse apps consist of

modular “plug-ins” “…plug-ins are the

fundamental unit for packaging function” (source: Platform Plug-in Developer Guide)

Also called “OSGi™ bundles” (Eclipse 3.1 onward)

Primarily in eclipse/plugins directory


Typical doc plug-in anatomy

Contents of plug-in: Help Contents topics

(HTML, XHTML files) Table of Contents files

(“toc.xml”) Keyword index files

(“index.xml”) Contextual help content

(“contexts.xml”) plugin.xml file MANIFEST.MF file

plugin.xml and MANIFEST.MF files describe the plug-in


Doc plug-in creation Some authoring tools generate doc

plug-in’s files (or most of the files) as part of their work flow

Or you assemble and package the doc plug-in

a. Create the files for the doc plug-inb. Collect the files into the defined directory

structure.c. Jar it up into a .jar filed. Deploy into Eclipse environment


Using Eclipse PDE to create a doc plug-in (demo)

In PDE environment, use File -> New -> Other, and choose Plug-in Project to create a new plug-in.


Using Eclipse PDE to test a doc plug-in

1. Right-click on your plug-in project and select Run As -> Eclipse Application.

2. New instance of Eclipse Workbench will start up.

3. Go to Help -> Help Contents in the new instance to open the help window and see your doc plug-in in the ToC.

4. After checking your plug-in, shut down the newly opened windows.


Plug-in id conventions

Organization

Bundle-SymbolicName (id) Examples

Public company

com.<companyname>.<abc>

com.oxygenxml.editorcom.ibm.eou.tmtool

Non-profit/open source

org.<orgname>.<abc> org.eclipse.pde.uiorg.objectweb.asm

Conventions for plug-in id/Bundle-SymbolicName

The plug-in id (Bundle-SymbolicName) is how the runtime environment identifies the module among all other plug-ins


Plug-in .jar naming conventions

Before Eclipse 3.2

<plugin-id>_<plugin-version>.jar

After Eclipse 3.2 <Bundle-SymbolicName>_<Bundle-Version>.jar

Valid plug-ins:org.eclipse.platform_1.0.3.jar jar fileorg.eclipse.pde.doc.user.jar jar filecom.lak.test1.doc directory

Recommended, not required


Some tools for generating doc plug-in files Frame -> Omni Systems Mif2Go Word, Frame, DITA -> WebWorks

ePublisher XMetal® Author Enterprise DITA Open Toolkit IXIASOFT’s DITA CMS solution Eclipse Plug-in Development

Environment (PDE)


Another methoda. Author XHTML topic files in

XHTML/HTML toolb. Author toc.xml files in XML-aware tool

or in PDEc. Author index.xml file in XML-aware toold. Create plugin.xml and MANIFEST.MF

files in PDEe. Assemble and package jar


Yet another methoda. Create TOC and index files in a

well-formed format (ideally XML)b. Transform into Eclipse toc.xml

and index.xml files via script or search and replace

Example: JavaHelp toc.xml and index.xml files


Working with your development teams

Contextual help contexts.xml maps context IDs to brief descriptions

and links to help topics Programmer’s code plug-in defines context ID Evangelize creating context IDs during

design/develop activity Cheat sheets

Development will usually program these Review task flow for them Provide links into help topics

Welcome pages Determine plan for whether and how to exploit


Asking questions in the community Yahoo!Group: eclipse_tw

Primarily technical writers Since 2004 http://groups.yahoo.com/group/eclipse_tw/

Newsgroup eclipse.platform.ua Since 2007 For instructions on how to access, see

Eclipse NewsPortal (www.eclipse.org/newsportal/index.php)

http://groups.yahoo.com/group/eclipse_tw/

http://www.eclipse.org/newsportal/index.php


Seek simplicity! Provide doc plug-ins for

Help Contents Have a way to generate

the doc plug-in files Assess your scenario’s

contextual help needs and plan accordingly Dynamic help section of

the Help View can help here


Thank you! You can be

successful in delivering Eclipse help

You can be a hero to your team!


Bonus Section Help Contents tips & gotchas Looking under the hood To learn more and locate expertise Useful references Using Eclipse Bugzilla to report bugs

and request new features Eclipse is… Why is Eclipse attractive to developers


Help Contents tips & gotchas Search is "tied" to ToC contributions

(toc.xml) Only files referenced in toc.xml are indexed for

search, or those from extradir attribute Search results displays topic’s <title> text

(not <h1> or <topic> label) Consider using <title> text distinct from the

<topic> label text for that topic Use <meta name="keyword"

content="…"/> tag in topics to add synonyms for user searches


Help Contents tips & gotchas (cont.) Avoid using anchors in toc.xml

Breadcrumb trail gets broken “Show in TOC” breaks when it can’t match right

hand frame’s URL#anchor with a ToC topic href Example: Index word has one anchor and ToC

topic has a different anchor Be sensitive to case-sensitivity (Win vs

Linux) <topic href="My_Guide.htm" /> ≠ <topic

href="my_guide.htm" />


Help Contents tips & gotchas (cont.) Use HTML "wrapper" topics for non-

HTML content When you want to include PDFs, Flash,

PPT content in the help system Have an HTML topic that has brief

description and anchor to non-HTML file Use <meta name="keyword"

content="…"/> tag in HTML file to specify search terms


Help Contents tips & gotchas (cont.)

Presentation of non-HTML contentPDF bookmarks open next to help system table of contents looks weird.

Solution:Open PDF in a separate window by using the <body onload> event (JavaScript) to open a new window outside the help system frameset.


Looking under the hood Useful for debugging Configuration markup for

MANIFEST.MF plug-in.xml toc.xml index.xml contexts.xml


Basic MANIFEST.MF structure

Manifest-Version: 1.0Bundle-ManifestVersion: 2Bundle-Name: Bear GuideBundle-SymbolicName: com.lak.test1.doc;singleton:=trueBundle-Version: 1.1.2Bundle-Vendor: Lee Anne Kowalski

Before 3.1, plugin.xml holds 3.1+, MANIFEST.MF holdsnameidversionprovider-name

Bundle-NameBundle-SymbolicNameBundle-VersionBundle-Vendor


Basic plugin.xml structure (3.1+) for doc plug-in

<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.2"?><plugin><!– extension points this plug-in plugs into --><extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension></plugin>

MANIFEST.MF file holds other plug-in identifying info (e.g., id, version)Extension points are well-defined places where other plug-ins can add (“plug in”) functionality.


Basic plugin.xml structure (3.0) for doc plug-in

<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin name=“Bear Guide” id=“com.lak.test1.doc” version=“1.1.2” provider-name=“Lee Anne Kowalski”><!–- extension points this plug-in plugs into --><extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension></plugin>


toc.xml structure<?xml version="1.0" encoding="UTF-8"?><?NLS TYPE="org.eclipse.help.toc"?><toc label="Guide to Bears" topic="html/welcome.html"> <topic href="html/intro/intro.html" label="Introduction to bears"> <topic href="html/intro/whatis.html" label="What is a bear"> </topic> <topic href="html/intro/where.html" label="Where do bears live"> </topic> <topic href="html/intro/food.html" label="What do bears eat"> </topic> </topic>...</toc>


index.xml structure<?xml version="1.0" encoding="utf-8"?><?NLS TYPE="org.eclipse.help.index"?><index><entry keyword=“bear types"> <entry keyword=“polar”> <topic href=“html/types/polar.html"/> </entry> <entry keyword=“grizzly"> <topic href=“html/types/grizzly.html"/> </entry></entry></index>


contexts.xml structure<?xml version="1.0" encoding="UTF-8"?><?NLS TYPE="org.eclipse.help.contexts"?>

<contexts><context id="toc_editor"><description>This editor creates a Help table of contents, which allows you to organize how documentation is displayed to users of an Eclipse product.</description><topic label="Table of Contents Editor" href="guide/tools/editors/toc_editor/editor.htm"/></context><context id="ctx_help_editor" title="Context Help Editor">…</context>…</contexts>

Doc plug-in’s plugin.xml structure (one ToC, one index)

<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin> <extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension><!– Define index file --> <extension point="org.eclipse.help.index"> <index file="index.xml" /></extension></plugin>

primary =“true” makes this ToC appear as a ‘book’ on the main level in the ToC view

Doc plug-in’s plugin.xml structure (multiple ToC, index files)<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin> <extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" />  <toc file="topics_GettingStarted.xml" /> <toc file="topics_Reference.xml" /> </extension><!– Define index file --> <extension point="org.eclipse.help.index"> <index file="Getting_started_idx.xml" /> <index file="Reference_idx.xml" /></extension>

Here, secondary ToCs are ones contained in this doc plug-in, that can be displayed in nested branches of the ToC

Doc plug-in’s plugin.xml structure with index, contextual help

<?xml version="1.0" encoding="UTF-8"?><?eclipse version="3.0"?><plugin> <extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /></extension><!– Define keyword index file --> <extension point="org.eclipse.help.index"> <index file="index.xml" /></extension><!– Define F1 context files --> <extension point="org.eclipse.help.contexts"> <contexts file="contexts.xml" plugin="com.lak.ui" /> </extension>


To learn more and locate expertise eclipse_tw Yahoo!Group Eclipse NewsPortal (

www.eclipse.org/newsportal/index.php) UA newsgroup: eclipse.platform.ua Also see eclipse.newcomer, eclipse.platform

Eclipse for Total Beginners (http://dev.eclipse.org/blogs/wayne/2007/07/25/eclipse-and-java-for-total-beginners/)

Eclipse Live! webinars (live.eclipse.org) Eclipse training (www.eclipse.org/users/)

http://www.eclipse.org/newsportal/index.php

http://dev.eclipse.org/blogs/wayne/2007/07/25/eclipse-and-java-for-total-beginners/

http://dev.eclipse.org/blogs/wayne/2007/07/25/eclipse-and-java-for-total-beginners/

http://www.eclipse.org/users/


Official Eclipse pages Eclipse.org (www.eclipse.org) Eclipse.org Wiki (http://wiki.eclipse.org/Main_Page) Eclipse docs on the Web (www.eclipse.org/documentation/) Eclipse UA development team’s page (

www.eclipse.org/eclipse/platform-ua/main.html) Eclipse Documentation (when you’re a member of an Eclipse

open-source project. http://wiki.eclipse.org/index.php/Eclipse_Documentation)

http://www.eclipse.org/

http://wiki.eclipse.org/Main_Page

http://www.eclipse.org/documentation/

http://www.eclipse.org/eclipse/platform-ua/main.html

http://wiki.eclipse.org/index.php/Eclipse_Documentation


You might be interested in “Adding Help Support to a Rich Client Platform (RCP) Application”

by Goldthorpe and Archer (Based on Eclipse 3.3, Written Oct. 2005. At Eclipse Corner Articles: http://www.eclipse.org/articles/)

“Writing Documentation and Help for Eclipse Projects and Plug-ins” (can be a little dated, good walk through of doc plug-in elements. www.keycontent.org/tiki-index.php?page=Eclipse%20Help%20System)

“An introduction to Eclipse for Microsoft® Visual Studio® users” (www.ibm.com/developerworks/opensource/library/os-eclipse-visualstudio/)

“The Heart of Eclipse” by Dan Rubel (Based on Eclipse 3.2. Written Oct. 2006. www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=425&page=1)

http://www.eclipse.org/articles/

http://www.keycontent.org/tiki-index.php?page=Eclipse%20Help%20System

http://www.keycontent.org/tiki-index.php?page=Eclipse%20Help%20System

http://www.ibm.com/developerworks/opensource/library/os-eclipse-visualstudio/

http://www.ibm.com/developerworks/opensource/library/os-eclipse-visualstudio/

http://www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=425&page=1

http://www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=425&page=1


Reporting bugs/requesting new features Eclipse Bugzilla

For both reporting bugs (defects) and filing feature requests

Bugzilla home: https://bugs.eclipse.org/bugs/

Need to have a Bugzilla account to report bug/request feature

https://bugs.eclipse.org/bugs/


Using Bugzilla

Create Bugzilla account

Report a bug Request something new


Reporting a bugAs you go through the Bug Wizard’s questions, for reporting an Eclipse UA bug, choose: I am reporting a bug with = “Eclipse itself” Select the plugin/component = “Platform” On the final step page, Component = “User Assistance”

If reporting an Eclipse help doc bug, choose Component = “Doc”


Entering a feature request1. Choose “Enter an

enhancement/feature request” on the Bugzilla home page.

2. Choose “Platform” link on the subsequent page.

3. Choose Component = “User Assistance” in the final request form.


Eclipse is…

“Eclipse is an open source community whose projects are focused on building an extensible development platform, runtimes, and application frameworks for building, deploying and managing software across the entire software lifecycle.” (source: “New to Eclipse”, Eclipse Foundation, www.eclipse.org)


Legal notices Eclipse is a registered trademark of the Eclipse

Foundation. <oXygen/> is a registered trademark of SyncRO Soft Ltd. Sybase is a registered trademark of Sybase, Inc. OSGi is a trademark, registered trademark, or service

mark of the OSGi Alliance in the United States and other countries.

XMetal is a registered trademark of JustSystems, Corp. Microsoft, Windows, and Visual Studio are registered

trademarks of Microsoft Corporation in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

getting up to speed on eclipse user assistance

Technology