Getting Up To Speed on Eclipse ™ User Assistance Dr. Lee Anne Kowalski Telleltis Consulting [email_address]

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)

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?

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!

Seek simplicity!

Eclipse is… An open platform for building any type of application An open-source integrated development environment (IDE) A community

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

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

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

Help Contents tri-pane window

Contextual (embedded/F1) help

Welcome pages

Cheat sheets

Getting and starting the Eclipse Workbench (Windows) Download package from www.eclipse.org “ Classic” package good to start with Unzip using zip tool (issues with XP native extraction) Double-click eclipse.exe in the eclipse directory

Download package from www.eclipse.org

“ Classic” package good to start with

Unzip using zip tool (issues with XP native extraction)

Double-click eclipse.exe in the eclipse directory

The Workbench Eclipse 3.4 (“Ganymede”)

Make conscious choices Base UA choices on your “Going to Eclipse” scenario Target audience expectations and requirements

Base UA choices on your

“Going to Eclipse” scenario

Target audience expectations and requirements

Typical “going to Eclipse” scenarios Examples Data Tools Project (Sybase) Project owner/member Actuate BIRT Report Designer Create desktop app <oXygen/> ® XML Author Create Workbench plug-ins MyEclipse Enterprise Workbench Extend the Eclipse Workbench (IDE) Scenarios

<oXygen/> ® XML Author

Observed pairings Project owner/member Create desktop app Create Workbench plug-ins Extend the Eclipse Workbench (IDE) Scenarios Depends on the nature of the project Help Contents Optionally: Contextual help, cheat sheets, Welcome pages Help Contents Contextual help (audience dependent) Optionally: Cheat sheets Help Contents (topics, ToC, index) Contextual help Typically: Welcome pages Optionally: Cheat sheets Exploited UA mechanisms

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)

“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

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

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

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 Create the files for the doc plug-in Collect the files into the defined directory structure. Jar it up into a .jar file Deploy into Eclipse environment

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

Create the files for the doc plug-in

Collect the files into the defined directory structure.

Jar it up into a .jar file

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 Right-click on your plug-in project and select Run As -> Eclipse Application. New instance of Eclipse Workbench will start up. Go to Help -> Help Contents in the new instance to open the help window and see your doc plug-in in the ToC. After checking your plug-in, shut down the newly opened windows.

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

New instance of Eclipse Workbench will start up.

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

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

Plug-in id conventions 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 org.<orgname>.<abc> com.<companyname>.<abc> Bundle-SymbolicName (id) Examples Organization org.eclipse.pde.ui org.objectweb.asm Non-profit/open source com.oxygenxml.editor com.ibm.eou.tmtool Public company

Conventions for plug-in id/Bundle-SymbolicName

Plug-in .jar naming conventions Valid plug-ins: org.eclipse.platform_1.0.3.jar  jar file org.eclipse.pde.doc.user.jar  jar file com.lak.test1.doc  directory Recommended, not required < Bundle-SymbolicName >_< Bundle-Version >.jar After Eclipse 3.2 < plugin-id >_< plugin-version >.jar Before Eclipse 3.2

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)

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 method Author XHTML topic files in XHTML/HTML tool Author toc.xml files in XML-aware tool or in PDE Author index.xml file in XML-aware tool Create plugin.xml and MANIFEST.MF files in PDE Assemble and package jar

Author XHTML topic files in XHTML/HTML tool

Author toc.xml files in XML-aware tool or in PDE

Author index.xml file in XML-aware tool

Create plugin.xml and MANIFEST.MF files in PDE

Assemble and package jar

Yet another method Create TOC and index files in a well-formed format (ideally XML) Transform into Eclipse toc.xml and index.xml files via script or search and replace Example: JavaHelp toc.xml and index.xml files

Create TOC and index files in a well-formed format (ideally XML)

Transform into Eclipse toc.xml and index.xml files via script or search and replace

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

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 )

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 )

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

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!

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

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 &quot; tied &quot; 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= &quot; keyword &quot; content= &quot; … &quot; /> tag in topics to add synonyms for user searches

Search is &quot; tied &quot; 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= &quot; keyword &quot; content= &quot; … &quot; /> 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= &quot; My_Guide.htm &quot; /> ≠ <topic href= &quot; my_guide.htm &quot; />

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= &quot; My_Guide.htm &quot; /> ≠ <topic href= &quot; my_guide.htm &quot; />

Help Contents tips & gotchas (cont.) Use HTML &quot; wrapper &quot; 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= &quot; keyword &quot; content= &quot; … &quot; /> tag in HTML file to specify search terms

Use HTML &quot; wrapper &quot; 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= &quot; keyword &quot; content= &quot; … &quot; /> tag in HTML file to specify search terms

Help Contents tips & gotchas (cont.) Presentation of non-HTML content PDF 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.

Presentation of non-HTML content

Looking under the hood Useful for debugging Configuration markup for MANIFEST.MF plug-in.xml toc.xml index.xml contexts.xml

Useful for debugging

Configuration markup for

MANIFEST.MF

plug-in.xml

toc.xml

index.xml

contexts.xml

Basic MANIFEST.MF structure Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: Bear Guide Bundle-SymbolicName: com.lak.test1.doc ;singleton:=true Bundle-Version: 1.1.2 Bundle-Vendor: Lee Anne Kowalski Bundle-Name Bundle-SymbolicName Bundle-Version Bundle-Vendor name id version provider-name 3.1+, MANIFEST.MF holds Before 3.1, plugin.xml holds

Basic plugin.xml structure (3.1+) for doc plug-in <?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?> <?eclipse version=&quot;3.2&quot;?> <plugin> <!– extension points this plug-in plugs into --> <extension point =&quot;org.eclipse.help.toc&quot;> <toc file=&quot;toc.xml&quot; primary=&quot;true&quot; /> </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=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?> <?eclipse version=&quot;3.0&quot;?> <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 =&quot;org.eclipse.help.toc&quot;> <toc file=&quot;toc.xml&quot; primary=&quot;true&quot; /> </extension> </plugin>

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

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

contexts.xml structure <?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?> <?NLS TYPE=&quot;org.eclipse.help.contexts&quot;?> <contexts> <context id=&quot;toc_editor&quot;> <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=&quot;Table of Contents Editor&quot; href=&quot;guide/tools/editors/toc_editor/editor.htm&quot;/> </context> <context id=&quot;ctx_help_editor&quot; title=&quot;Context Help Editor&quot;> … </context> … </contexts>

Doc plug-in’s plugin.xml structure (one ToC, one index) <?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?> <?eclipse version=&quot;3.0&quot;?> <plugin> <!-- Define primary TOC --> <extension point=&quot;org.eclipse.help.toc&quot;> <toc file=&quot;toc.xml&quot; primary=&quot;true&quot; /> </extension> <!– Define index file --> <extension point=&quot;org.eclipse.help.index&quot;> <index file=&quot;index.xml&quot; /> </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=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?> <?eclipse version=&quot;3.0&quot;?> <plugin> <!-- Define primary TOC --> <extension point=&quot;org.eclipse.help.toc&quot;> <toc file=&quot;toc.xml&quot; primary=&quot;true&quot; /> <!-- Define secondary TOCs --> <toc file=&quot;topics_GettingStarted.xml&quot; /> <toc file=&quot;topics_Reference.xml&quot; /> </extension> <!– Define index file --> <extension point=&quot;org.eclipse.help.index&quot;> <index file=&quot;Getting_started_idx.xml&quot; /> <index file=&quot;Reference_idx.xml&quot; /> </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=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?> <?eclipse version=&quot;3.0&quot;?> <plugin> <!-- Define primary TOC --> <extension point=&quot;org.eclipse.help.toc&quot;> <toc file=&quot;toc.xml&quot; primary=&quot;true&quot; /> </extension> <!– Define keyword index file --> <extension point=&quot;org.eclipse.help.index&quot;> <index file=&quot;index.xml&quot; /> </extension> <!– Define F1 context files --> <extension point=&quot;org.eclipse.help.contexts&quot;> <contexts file=&quot;contexts.xml&quot; plugin=&quot;com.lak.ui&quot; /> </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/ )

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/ )

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 )

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 )

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 )

“ 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 )

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

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

Using Bugzilla Create Bugzilla account Report a bug Request something new

Reporting a bug As 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”

As 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 request Choose “Enter an enhancement/feature request” on the Bugzilla home page. Choose “Platform” link on the subsequent page. Choose Component = “User Assistance” in the final request form.

Choose “Enter an enhancement/feature request” on the Bugzilla home page.

Choose “Platform” link on the subsequent page.

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.

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.