EclipseLink/Development/Documentation/ELUG old

From Eclipsepedia

< EclipseLink‎ | Development‎ | Documentation
Revision as of 09:45, 31 October 2007 by Rick.sapir.oracle.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.

For Release 2.0

  • EclipseLink User's Guide will be updated to include new R2 functionality, as needed
  • Incorporate community collaborations from Wiki pages


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


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