© 2008 by Motorola Inc.; made available under the EPL v1.0 | Match 19th, 2008 |

Building XML-based Content for Eclipse Help: a Real Experience

Christian Kurzke

Gustavo de Paula

Daniel Moura

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Agenda

• MOTODEV for JavaME Tools• Documentation Requirements• Types of Documentation• Content Source• Content Transformation• Eclipse Help Structure• Conclusion

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

MOTODEV Tools for JavaME

• Full JavaME IDE• Based on Eclipse Platform+ JDT +

EclipseME• Includes an UEI JavaME Emulator• Support most of MIDP 2.0 Motorola

devices• Includes complete documentation

about the Devices and the APIs• Include external tools that support

the development• Includes demo of JavaME APIs

• SDK that can be integrated on any UEI compliant IDE

• Based on Eclipse RCP• Includes an UEI JavaME Emulator• Support most of MIDP 2.0 Motorola

devices• Includes complete documentation

about the Devices and the APIs

• Include external tools that support the development

• Includes demo of JavaME APIs

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Documentation Requirements

• There are different types of documentation that needs to be included on the tools

• Most of the documentation is shared between both tools, but there are some parts that are specific to each tool

• Deployment format independency PDF versions of the documentation to be placed on MOTODEV

Website Help plug-ins content

• Eclipse Help plug-ins build must be integrated on the main product builds

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Types of Documentation

• Distinct types of documentation were identified API Guides JavaDocs Device Matrix Spec sheets User guides Tips and Tricks Cheat sheets

• Some of the types are reused in both tools

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Types of Documentation• Documentation was broken into two main groups

Tool specific documentation Device specific documentation

• Each tool has its own documentation feature (docs.tools.studio and docs.tools.sdk)

• Device common documentation has its one feature (docs.device)• Each type of documentation is pack in its own plugin

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Content Source Format

• Already defined i.e. Javadocs

• Deployment format independent API Guides Spec sheets

• Use an XML-based format There are already some solutions for that (DITA, Docbook,

etc.)

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Content Source Format

• In-house XML framework Originally used only to generate PDFs (since 2002) Later extended to generate HTMLs

• Framework defines XML schema Set of templates (transformations) for each type of content

that generates PDFs Set of templates (transformations) for each type of content

that generates HTMLs

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Content Transformation

Transformation is executed during Tool build process

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Content Transformation – API Guide Transformation

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Content Transformation – Directory View

Each content type has its own buildXML and images represent the content

Transformation frameworkUsed by each content that needs transformationPDE build is then used to generate plug-ins

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Eclipse Help Structure

Device specific documentation (common)

Tool specific documentation

Building XML-based content for Eclipse Help: a real experience | © 2008 by Motorola Inc. ; made available under the EPL v1.0

Conclusion

• XML based content is a good way to write Eclipse Help

• There are existing solutions that can be used to maintain and transform existing content to fit the Eclipse Help structure

• The content structure is quite complex to organize and the effort to create Help content must not be underestimated