Your SlideShare is downloading. ×
0
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Getting Up to Speed on Eclipse User Assistance
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Getting Up to Speed on Eclipse User Assistance

2,319

Published on

Version presented at the conference.

Version presented at the conference.

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
2,319
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
49
Comments
0
Likes
2
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide
  • Transcript

    • 1. Getting Up To Speed on Eclipse ™ User Assistance Dr. Lee Anne Kowalski Telleltis Consulting [email_address]
    • 2. 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)
    • 3. 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?”
    • 4. 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?
    • 5. First time out
      • Seek simplicity!
    • 6. Eclipse is… An open platform for building any type of application An open-source integrated development environment (IDE) A community
    • 7. 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
    • 8. 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
    • 9. 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
    • 10. The Workbench Eclipse 3.4 (“Ganymede”)
    • 11. Make conscious choices
      • Base UA choices on your
        • “Going to Eclipse” scenario
        • Target audience expectations and requirements
    • 12. 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
    • 13. 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
    • 14. 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)
    • 15. 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
    • 16. 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
    • 17. 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
    • 18. 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.
    • 19. 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.
    • 20. 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
    • 21. 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
    • 22. 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)
    • 23. 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
    • 24. 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
    • 25. 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
    • 26. 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 )
    • 27. 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
    • 28. Thank you!
      • You can be successful in delivering Eclipse help
      • You can be a hero to your team!
    • 29. 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
    • 30. 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
    • 31. 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; />
    • 32. 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
    • 33. 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.
    • 34. Looking under the hood
      • Useful for debugging
      • Configuration markup for
        • MANIFEST.MF
        • plug-in.xml
        • toc.xml
        • index.xml
        • contexts.xml
    • 35. 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
    • 36. 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.
    • 37. 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>
    • 38. 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>
    • 39. 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>
    • 40. 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>
    • 41. 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
    • 42. 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
    • 43. 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>
    • 44. 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/ )
    • 45. 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 )
    • 46. 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 )
    • 47. 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
    • 48. Using Bugzilla Create Bugzilla account Report a bug Request something new
    • 49. 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”
    • 50. 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.
    • 51. 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)
    • 52. 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.

    ×