Difference between revisions of "EclipseLink/Development/Documentation/Requirements"

From Eclipsepedia

Jump to: navigation, search
m (U5. Images)
m
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
'''Note: Starting with 2.4, all EL documentation is published in the EL Doc Center: www.eclipse.org/eclipselink/documentation/ '''
 +
 
== EclipseLink Documentation Requirements ==
 
== EclipseLink Documentation Requirements ==
  
Line 48: Line 50:
 
==== U4. Source ====
 
==== U4. Source ====
 
How are we distributing source attached to the documentation?  This is mostly an issue only for tutorials and examples and not the ELUG.
 
How are we distributing source attached to the documentation?  This is mostly an issue only for tutorials and examples and not the ELUG.
==== U5. Images ====
 
*We need guidelines for inline images (screen captures and UML diagrams) specific to size, format (png|jpg|gif), scrubbing of identifiable data/IP's, searchable captions/descriptions, storage of original source (for UML I use Visio and extract to JPG).
 
*As mentioned in the 20100128 meeting - the namespace for image names is flat (IE: there can be only one uml_diagram.gif across the entire eclipse.org wiki.  We therefore require a naming convention to circumvent this issue.
 
**I propose paraphrasing the wiki address in the image name.
 
==== U6. Linking ====
 
*Guidelines are required for how we link between official ELUG documentation and more informal wiki examples, tutorials and general development wiki pages.
 
*There are currently links to content from the ELUG to the tutorials and vice-versa to avoid content duplication
 
*Broken links: When a link to a specific section is broken because the title has changed - the user will arrive at the top of the page.  We therefore need to be carefull when choosing major section names.
 
*Duplicated title names: The current wiki does not check for duplicated title names (IE: two sections called "Results").  The user will arrive at the first link found - we therefore need to make each section title '''unique'''.
 
  
 
=== Contributors ===
 
=== Contributors ===
Line 99: Line 92:
 
* ??
 
* ??
  
== Proposal ==
+
==== C4. Images ====
 +
*We need guidelines for inline images (screen captures and UML diagrams) specific to size, format (png|jpg|gif), scrubbing of identifiable data/IP's, searchable captions/descriptions, storage of original source (for UML I use Visio and extract to JPG).
 +
*As mentioned in the 20100128 meeting - the namespace for image names is flat (IE: there can be only one uml_diagram.gif across the entire eclipse.org wiki.  We therefore require a naming convention to circumvent this issue.
 +
**I propose paraphrasing the wiki address in the image name.
 +
 
 +
==== C5. Linking ====
 +
*Guidelines are required for how we link between official ELUG documentation and more informal wiki examples, tutorials and general development wiki pages.
 +
*There are currently links to content from the ELUG to the tutorials and vice-versa to avoid content duplication
 +
*Broken links: When a link to a specific section is broken because the title has changed - the user will arrive at the top of the page.  We therefore need to be carefull when choosing major section names.
 +
*Duplicated title names: The current wiki does not check for duplicated title names (IE: two sections called "Results").  The user will arrive at the first link found - we therefore need to make each section title '''unique'''.
 +
 
 +
== Agreed Upon Proposal ==
  
 
=== Infrastructure ===
 
=== Infrastructure ===
  
* EclipseLink User Guide (ELUG) documentation will be stored in SVN as XML files.
+
* EclipseLink User Guide (ELUG) documentation will be stored in SVN as XML files. <br> http://dev.eclipse.org/viewsvn/index.cgi/branches/2.0/trunk/documentation/?root=RT_Eclipselink
 
* Files should conform to DocBook DTD. <br />  
 
* Files should conform to DocBook DTD. <br />  
 
<source lang="xml">
 
<source lang="xml">
Line 109: Line 113:
 
   PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
   PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
</source>
 
</source>
 
  
 
=== Process ===
 
=== Process ===
Line 137: Line 140:
  
 
=== Editorial Standards ===
 
=== Editorial Standards ===
*
+
* pending
 
*
 
*
  
Line 144: Line 147:
 
=== Specific Deliverables ===
 
=== Specific Deliverables ===
 
* [http://wiki.eclipse.org/EclipseLink/Development/Documentation/JPA EclipseLink JPA User Guide]
 
* [http://wiki.eclipse.org/EclipseLink/Development/Documentation/JPA EclipseLink JPA User Guide]
 +
 +
== Build Process ==
 +
Goal: To produce daily (or regular) "snapshots" of the EclipseLink documentation (in PDF and HTML fomats) and publish these documents to public areas of the EclipseLink web site.
 +
 +
Benefit: This allows contributors to create "live" documentation in parallel with application development.
 +
Reviewers are assured of always using the current/latest documentation. Process will be auotmated.
 +
 +
=== Requirements ===
 +
* Install OpenOffice (Linux) on build machine<br />Eric to check with Eclipse webmaster on this
 +
* Store all XML files (individual chapters) in SVN. <br />Rick has already checked in several XML files
 +
* Store the OpenOffice "master" document file (ODM) in SVN.<br />This is an OpenOffice file th
 +
 +
=== Proposed Process ===
 +
As discussed previously:
 +
# Contributors check in XML files (representing chapters or sections of the book.
 +
# Contributors check in ODM files (containing the chapter order, master table of contents, layout and design.
 +
# As part of build process, OpenOffice ODM file is opened (via command line). Using Export and/or Save As process, OpenOffice generates a PDF and set of HTML files.
 +
# The generated documents are added to the EclipseLink web page. Notification of the doc build is included with the regular build process.
 +
 +
 +
 +
=== Open Issues ===
 +
* Can we install OpenOffice on the build machine? (Eric)
 +
* Can we checkout the latest XML, ODM, and PNG files, generate a PDF and HTML, and publish to web site? (Doug - need a location to publish docs in process. Should they be "bundled with the daily build, or stored separately? If separate, how long should we store old doc builds?
 +
* Licensing - Since we are using OpenOffice as our build application, we're using OpenOffice master files (ODM) to maintain book-wide information. Each book (and publisher: Oracle, SAP, etc.) will have its own ODM file.

Latest revision as of 10:04, 22 February 2013

Note: Starting with 2.4, all EL documentation is published in the EL Doc Center: www.eclipse.org/eclipselink/documentation/

[edit] EclipseLink Documentation Requirements

This page captures the requirements for future versions of the EclipseLink User Guide (ELUG). This is a work in progress. See Release 1.0 Doc Plan for background on the original ELUG plan.

Contents


[edit] Users

These requirements are for the consumers of the EclipseLink documentation which includes both the community using EclipseLink from eclipse.org as well as companies who redistribute EclipseLink and want to include or link to the ELUG.

[edit] U1. Version Specific

Each release and patch-set of EclipseLink should be able to offer ELUG content that is version specific.

  • Provide links to ELUG for a specific version that navigates only to pages with content for this version
  • Each release notes page (wiki) will link to the main

[edit] U2. Technology Specific Documents/Books

The documentation must be organized into technology (persistence service) specific document sets/books.

  • JPA: Content focused on using EclipseLink JPA along with its advanced features
    • Native API usage shown only in the ?
  • MOXy: Content focused on EclipseLink MOXy usage including JAXB annotations, native eclipselink-oxm.xml and native API configuration and usage
  • SDO: Content focused on EclipseLink SDO
    • May make sense to combine with MOXy
    • DAS (SDO-JPA bridge using MOXy) should be covered and can link to JPA content as necessary
  • DBWS

Common Requirements for all sets/books:

  • The content of each set/book can share content but should be presented in the context of the technology being covered and avoid generic content containing links to its use in a variety of technologies - we should discuss this one
    • Tutorials for example, have sections (like how to get EclipseLink source) that are duplicated in-line for each application server - with shared content we can generate these common sections from one place.

[edit] U3. Consumable

It would be nice to enable the version specific ELUG content to be consumable into other documentation sets. Products and other projects that include EclipseLink should be able to consume the specific version of the ELUG matching the version they include.

Example: Oracle TopLink, Oracle WebLogic, GlassFish, and SAP NetWeaver do or will ship EclipseLink. Ideally these projects/products want to embed the version specific ELUG into their overall documentation set so that their end users have a consistent experience using their documentation.

Should:

  • Support producing an HTML and/or PDF documentation output for a specific EclipseLink version that consumers can use
  • License the content under a license that enable consumers to include--the Eclipse Foundation has endorsed a Creative Commons license for non-code artifacts--need to use approved license.

Nice to Have:

  • Enable consumers to skin the documentation for their own Look & Feel
  • Enable consumers to include and cross-link into the content from their own content that wraps the ELUG
  • Enable packaging as Eclipse IDE on-line help for inclusion with distributions that include EclipseLink components.
  • Support producing an HTML and/or PDF documentation for a specific EclipseLink functional area.

[edit] U4. Source

How are we distributing source attached to the documentation? This is mostly an issue only for tutorials and examples and not the ELUG.

[edit] Contributors

This section captures the requirements of the content producers. The goal is to streamline content development addressing the complex nature of the software spanning multiple technologies with shared infrastructure and thus common functionality.

[edit] C1. Open

The content must be developed in an open fashion so that any interested party can participate in the development and ongoing maintenance of the ELUG.

  • Content must be developed in a repository that is generally accessible over the internet
  • Content stored in an "open" format (i.e., XML)
  • Content format conforms to an established standard (DITA or Docbook?)
  • Approved content developers from any organization must be able to have write access to the repository. Generally this involves contributors providing documentation fixes and enhancements through bugs and the document authors being project committers having write access to the content repository
    • Alternative is to allow project committers to provide doc updates directly to the the repository, similar to how we currently allow any committer to update the end-user wiki content.
      • Developer committers that post extensive updates to the wiki content will require the same write access to the new repository - the issue is how to formalize the review process of content that is geared to the end user (outside of the ELUG) that is authored by these committers - currently a request is sent by mail just like a code review.

[edit] C2. Simplify

The content authors need to be able to manage the content in an efficient manor.

Nice To Have:

  • Single repository where all content is managed and authors simply add and enhance without duplication of effort
  • Content is tagged with the versions it is relevant to. This enables new content to be added for older functionality and have it picked up in all applicable versions of ELUG when next generated.
    • Also allows end users to dynamically query the repository and build "custom" deliverables on-the-fly
  • Content is stored by topic (i.e., information-centric) rather than by page or chapter (i.e., book-centric)


[edit] C3. Tools

  • Content authors (contributors) should be able to use any tool that can produce valid XML for storage in the repository.
  • Need a tool that can query the repository and "build" end-user deliverables

Open Source tools


Commercial Tools

[edit] C4. Images

  • We need guidelines for inline images (screen captures and UML diagrams) specific to size, format (png|jpg|gif), scrubbing of identifiable data/IP's, searchable captions/descriptions, storage of original source (for UML I use Visio and extract to JPG).
  • As mentioned in the 20100128 meeting - the namespace for image names is flat (IE: there can be only one uml_diagram.gif across the entire eclipse.org wiki. We therefore require a naming convention to circumvent this issue.
    • I propose paraphrasing the wiki address in the image name.

[edit] C5. Linking

  • Guidelines are required for how we link between official ELUG documentation and more informal wiki examples, tutorials and general development wiki pages.
  • There are currently links to content from the ELUG to the tutorials and vice-versa to avoid content duplication
  • Broken links: When a link to a specific section is broken because the title has changed - the user will arrive at the top of the page. We therefore need to be carefull when choosing major section names.
  • Duplicated title names: The current wiki does not check for duplicated title names (IE: two sections called "Results"). The user will arrive at the first link found - we therefore need to make each section title unique.

[edit] Agreed Upon Proposal

[edit] Infrastructure

<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

[edit] Process

Contributors can use any application to edit or update the documentation files, as long as the application's XSLT is compatible with the DTD. The recommended tool is OpenOffice.

  1. Install the necessary import and export XSLT stylesheets (available from OpenOffice.org).
  2. Obtain the OpenOffice.org Template required for DocBook Article and Chapter documents from OpenOffice.org.
  3. Create a new DocBook filter:
    • Go to Tools -> XML Filter Settings...
    • Create a new filter with "New..." button
    • Set Filter Name and Name of File Type to DocBook (Chapter)
    • Go to the Transformation tab
    • Set DocType to <chapter>
      • For XSLT for Export browse to the chapter export stylesheet (sofftodocbookheadings_chapter.xsl).
      • For XSLT for Import browse to the chapter import stylesheet (docbooktosoffheadings.xsl).
      • For Template for Import browse to the style template (DocBookTemplate.stw).
    • Click OK and close the XSLT Filter Setting dialog
  1. Obtain the need XML files from SVN (i.e., the chapters).
  2. Create a new OpenOffice Master Document (.ODM). This allows you to create a "customized" EL User Guide that contains only the content you need.
  3. Add the chapters to the Master Document.
  4. Edit the individual chapters, including the styles, as necessary. When saving the chapter files, OpenOffice may display the following message:
    Be sure to select Keep Current Format.
    • Alternatively, you can select Save As... and select DocBookXML from the Save As dialog.
  1. Check-in the XML files to SVN.
    Do not check-in your Master Document file (.ODM)
    Note: The "official" EclipseLink User Guide master file (ODM) will be maintained in SVN.

[edit] Editorial Standards

  • pending


[edit] Specific Deliverables

[edit] Build Process

Goal: To produce daily (or regular) "snapshots" of the EclipseLink documentation (in PDF and HTML fomats) and publish these documents to public areas of the EclipseLink web site.

Benefit: This allows contributors to create "live" documentation in parallel with application development.

Reviewers are assured of always using the current/latest documentation. Process will be auotmated.

[edit] Requirements

  • Install OpenOffice (Linux) on build machine
    Eric to check with Eclipse webmaster on this
  • Store all XML files (individual chapters) in SVN.
    Rick has already checked in several XML files
  • Store the OpenOffice "master" document file (ODM) in SVN.
    This is an OpenOffice file th

[edit] Proposed Process

As discussed previously:

  1. Contributors check in XML files (representing chapters or sections of the book.
  2. Contributors check in ODM files (containing the chapter order, master table of contents, layout and design.
  3. As part of build process, OpenOffice ODM file is opened (via command line). Using Export and/or Save As process, OpenOffice generates a PDF and set of HTML files.
  4. The generated documents are added to the EclipseLink web page. Notification of the doc build is included with the regular build process.


[edit] Open Issues

  • Can we install OpenOffice on the build machine? (Eric)
  • Can we checkout the latest XML, ODM, and PNG files, generate a PDF and HTML, and publish to web site? (Doug - need a location to publish docs in process. Should they be "bundled with the daily build, or stored separately? If separate, how long should we store old doc builds?
  • Licensing - Since we are using OpenOffice as our build application, we're using OpenOffice master files (ODM) to maintain book-wide information. Each book (and publisher: Oracle, SAP, etc.) will have its own ODM file.