Jump to: navigation, search

EclipseLink/Development/Documentation/ELUG old

Future of the ELUG on the EclipseLink wiki

Documentation Goals

  1. Usability - easy to find content using search and content organization including categories, hierarchies, and links
  2. Organize content based on tasks - Configuration, Mapping, Caching, Querying, Monitoring/profiling, Optimizing, packaging/Deploying
  3. Combine ORM topic based functionality so common theory is shared with JPA and native-ORM
  4. Isolated all Workbench specific content from JPA/Native-ORM
  5. Address version specific content clearly yet focus on newest functionality first (JPA2, JPA1, nativeORM). Ideally users of a specific version can find their content with minimal clutter of new version content. If a new version's feature requires greater then X% of a page to change we should look into refactoring the content to better isolated the features being extended.
  6. Continue to allow community participation in the evolution of the wiki documentation. We should clearly document our expectations however and ensure that all doc pages are watched so content changes are known and verified.
  7. Address offline usage of the documentation. This could be PDF or offline caching of specific doc pages. In either case the usability of the produced documentation must be maintained or enhanced.

Producing PDFs from ELUG wiki content

I (Rick) have explored several possibilities to convert wiki content (http://wiki.eclipse.org/EclipseLink/UserGuide) into PDF books and have summarized the results and my observations:

  1. Create PDFs by using the "printer version" of the existing wiki pages.
    Pro: Easy (simply go to each wiki page, select the Printable Version, then Save As... PDF).
    Con: We'll get 160+ separate PDF files that will have to be manually merged into a single book. No intra-linking. No overall TOC or IX. Page formatting cannot be customized.
  2. Using Eclipse+Mylyn to convert wiki syntax to HTML, then generate PDFs
    Pro: Easy (simply import each wiki page, convert to HTML, then print to PDF). Can create a custom CSS to better control page formatting. Mylyn provides application and scripting support, so we could automate many steps.
    Con: Would need dev resources for application customization. Images have to be downloaded separately. Any "generated" content (such as TOC boxes) are lost.
  3. Use FrameMaker (our publishing tool) as the "source" material, from which to generate PDFs and HTMLs. (This is the current method for producing Dali documentation.
    Pro: Gives us complete control over page formatting. The FM->PDF and FM->HTML converters are supported by Oracle ST Doc group. Can export from FM->HTML->Wiki. The FM source files can be added to SVN for version control. Can create scripts to create daily "builds" of PDF, HTML,and Wiki files.
    Con: We would have to convert all wiki pages into Framemaker (manual process, est. 6-8 weeks). The Wiki files would no longer be community developable -- we would be overwriting them (daily) from the pages generated from the FM source files. Community could no longer edit/update documentation directly; only the people with Frame Maker could edit/update the original source files.
  4. Use MediaWiki extensions that allow for the creation of PDFs based on categories (or single pages).
    Pro: Native MediaWiki solution, allows us to continue using the Wiki "as is." Through the use of categories we could potentially create "customized" ELUG guides (e.g., all pages in JPA category).
    Con: The current wiki pages cross multiple categories (due to the original "dump" from JITDG). Requires support from Eclipse webmaster to install the extension and its prerequisites.
  5. Duplicate the wiki content and create a separate wiki namespace for each release.
    Pro: Native MediaWiki solution, allows us to continue using the Wiki "as is." Would have a "frozen" wiki version for each EclipseLink release.
    Con: Requires support from Eclipse webmaster. I have requested new namespaces in the past and was denied. Does not address the PDF creation issues (see #1 & #2, above).


EclipseLink Documentation Plan

For Release 1.0:

  • EclipseLink User's Guide will be created, based on the 11g Oracle TopLink Developer's Guide. The focus will be for end-users of EclipseLink.
    • Publish as HTML on the EclipseLink wiki (see EclipseLink/UserManual for a sample, proposed end-user documentation landing page.)
    • Create crosslinks to/from the EclipseLink Examples
    • Online help for the Eclipse Workbench will direct users to the User's Guide on the wiki.


Specific Deliverables

User's Guide Each wiki page of the User's Guide will be "tagged" to identify the content. These tags (intra-document links) will provide primary navigation among the wiki topics.

For example, a topic like "Configuring EclipseLink Cache Type Using persistence.xml" would be associated with the following categories:

  • Eclipselink User's Guide: Architecture: JPA
  • Eclipselink User's Guide: Version: 1.0
  • Eclipselink User's Guide: Type: Task
  • Eclipselink User's Guide: Status: Draft

This allows end-users to:

  • Ask "Just show me what I need to know about JPA" and not burden them with the whole encyclopedia
  • Quickly zero in on what they really want to know: I want to know how to "Do" something, so I'll look at the tasks; I want to know how to "Understand" something, so I'll look at the concepts
  • Automatically create lists of topics by category

This also allows contributors to:

  • Re-use topics across multiple categories.

An initial, proposed list of categories:

  • Release
    • 1.0
    • 2.0
  • Architecture
    • JPA
    • MOXy
    • EIS
    • XML
  • Topic Type
    • Task
    • Concept
    • Reference
  • Page Status
    • Draft
    • Published

Other Wiki Pages In addition to the documentation-specific wiki pages, we will create navigation (landing) pages to direct users to the specific information.

  • wizard-like guide to a landing page (summary page) that collects all the most relevant documentation links for the selected technology
  • We will also provide landing pages (i.e., multiple entry points), based on specific tasks. Consider the "what can I use EclipseLink for?" question. Based on this view, we would guide the user as follows:
    • What do you want to do with EclipseLink?
      • Persistence or Data Transformation
      • if Persistence then Spring or Java EE or Java SE
        • if Java SE then JPA or Native ORM or XRM or EIS
          • if JPA then: we present a landing page that serves as a starting point for building JPA applications outside of the container
          • list cross-references to relevant Examples
          • list relevant cross-references to the EclipseLink Users's Guide constrained to only JPA in Java SE

Fulltext search

  • Handled via wiki
  • Also added GCSE

Contributors Guidelines For people who want to contribute to the User's Guide (to include style guidelines, word usage, formatting etc.) Based on Eclipse_Doc_Style_Guide, modified for wiki-specifics

End-user Experience

EclipseLink end-users will access the documentation from the EclipseLink wiki.

  • End-user Documentation Landing Page - Provides the primary entry-point and contains the following sections:
    • Getting Started
      • List of topics constrained to those essential for a new user. These topics may include:
        • direct links to the primary areas.
        • Migration
        • Release notes
        • Tips and Tricks
        • Cheatsheets
        • Feature list
        • Legal
    • Learning More - Primary entry point into the User's Guide
      • List of topics constrained to more advanced, experimental tasks.
      • Links to Forums, Training, Support, Release Notes, Legal, etc.
    • Using EclipseLink - Primary entry point into specific Examples pages
      • Primary means of finding information based on technology and purpose (and other criteria).