Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/Development/Documentation/2.4"
m |
|||
Line 1: | Line 1: | ||
<H1>Documentation Plan for EclipseLink 2.4</H1> | <H1>Documentation Plan for EclipseLink 2.4</H1> | ||
− | Please complete comments on this doc plan by Thursday, August 25. | + | |
+ | |||
+ | '''''Please complete comments on this doc plan by Thursday, August 25.''''' | ||
+ | |||
+ | |||
<h2>Change Record</h2> | <h2>Change Record</h2> | ||
Line 203: | Line 207: | ||
<ul> | <ul> | ||
<li>All EclipseLink documentation will be maintained under the | <li>All EclipseLink documentation will be maintained under the | ||
+ | <i>Documentation Center</i> on the EclipseLink wiki at http://wiki.eclipse.org/EclipseLink/UserGuide">http://wiki.eclipse.org/EclipseLink/UserGuide. | ||
+ | </li> | ||
+ | <li>Versioning will be handled as follows:</li> | ||
+ | <ul> | ||
+ | <li>A note "New in EL 2.<i>n</i>" will be placed | ||
+ | next to new topics in the TOCs, where <i>n</i> refers to the release when | ||
+ | the feature was introduced. This is currently handled using template <span | ||
+ | style='font-family:"Courier New"'>{{EclipseLink/NewIn2<i>n</i>}}</span>.</li> | ||
+ | <li>A note " New in version 2.<i>n</i>." will be | ||
+ | added at the beginning of a topic documenting a new feature. This is | ||
+ | currently handled using <span style='font-family:"Courier New"'>{{EclipseLink_NewIn|version=2.n}}.</span></li> | ||
+ | <li>If a new feature is handled in an existing topic and the | ||
+ | topic changes more than 50%, the note " New in version 2.<i>n</i>." | ||
+ | will be placed at the beginning of the topic or at the beginning of the appropriate | ||
+ | section. </li> | ||
+ | <li>Header and footers on the wiki page will contain no | ||
+ | references to release numbers. </li> | ||
+ | <li>If a feature is deprecated, a note will placed next to | ||
+ | the documentation for the feature.</li> | ||
+ | </ul> | ||
+ | <li>Each topic will document one "feature." The term | ||
+ | "feature" here is somewhat loose. In some cases, it is a single | ||
+ | annotation. In some cases, the topic will document how to use multiple | ||
+ | annotations together for a specific purpose, e.g., single-table | ||
+ | multi=tenancy.</li> | ||
+ | <li>These topics are more-or-less "reference" | ||
+ | topics. That is, they document the primary APIs and XML used to implement | ||
+ | the feature. There can be limited discussion about how to use the code to | ||
+ | achieve the purpose of the feature, but we will not attempt to put the | ||
+ | feature in a larger context or to fully document all related features<span | ||
+ | style='color:red'>. </span></li> | ||
+ | <li>The JPA topics will primarily focus on using annotations, | ||
+ | when they are available. For example, a topic may begin with something | ||
+ | like, "Use the @Xyz annotation to…" and most or all examples and | ||
+ | code snippets will show annotations. When the feature can also be coded | ||
+ | using XML, the topic can discuss the XML (including a reference to the | ||
+ | schema), but the documentation for XML will not be as extensive as the | ||
+ | documentation for the annotation.</li> | ||
+ | <li>Every topic will cross-reference:</li> | ||
+ | <ul> | ||
+ | <li> Any associated example provided by Development and | ||
+ | located in the Samples section of the wiki.</li> | ||
+ | <li>Any associated Javadoc. When an annotation is available, | ||
+ | the reference will be to the annotation(s), not the "native | ||
+ | API."</li> | ||
+ | </ul> | ||
+ | <li>The Documentation team will not document features that are | ||
+ | not EclipseLink-specific. In particular, features that are documented in | ||
+ | the specification for the underlying technology. For example features | ||
+ | documented in the <i>JSR-000317 JavaTM Persistence 2.0</i> specification | ||
+ | will not be documented. However, anyone with permission to edit the wiki | ||
+ | may add topics to the wiki. As time permits, the Documentation team may | ||
+ | provide advice on the organization of topics. Any non-Documentation person | ||
+ | adding topics is responsible for adding and maintaining the following:</li> | ||
+ | <ul> | ||
+ | <li>Previous and Next browse sequence links at the bottom of | ||
+ | the page </li> | ||
+ | <li>Links from the Table of Contents</li> | ||
+ | <li>Links from the parent, or container, topic, if there is | ||
+ | one. For example, the JPA documentation includes a "Weaving | ||
+ | Topic" which introduces several weaving-related topics under it. </li> | ||
+ | </ul> | ||
+ | </ul> | ||
+ | |||
+ | <p style='margin-left:1.0in'>Note: A container topic should not | ||
+ | contain only a list of links. Every topic must include at least an overview | ||
+ | sentence. For example: "The EclipseLink cache is an in-memory repository | ||
+ | that stores recently read or written objects based on class and primary key | ||
+ | values. Caching is discussed in the following topics:"</p> | ||
+ | |||
+ | <ul> | ||
+ | <li>Individual topics will not include cross references to the | ||
+ | standard specifications (JPA, JAXB). There will be one overview topic (or | ||
+ | an overview topic for each service) that will contain the link to the | ||
+ | appropriate specification.</li> | ||
+ | <li>If design documents (specs) are not available or do not | ||
+ | contain enough source material (including examples), writers will file | ||
+ | bugs against Development via BugZilla.</li> | ||
+ | </ul> | ||
+ | |||
+ | <h2>Tasks/Deliverables</h2> | ||
+ | |||
+ | <p>The following tasks are not specifically associated with the | ||
+ | EclipseLink 2.4 release but will be handled by the Documentation team during | ||
+ | this period:</p> | ||
+ | |||
+ | <h3>General</h3> | ||
+ | |||
+ | <table border=1> | ||
+ | <tr> | ||
+ | <td> | ||
+ | <p><b><i>Task/Deliverable</i></b></p> | ||
+ | </td> | ||
+ | <td> | ||
+ | <p><b><i>Writer</i></b></p> | ||
+ | </td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td> | ||
+ | <p>Identify topics in the JPA TOC that are documented in the | ||
+ | JPA specification to clarify which existing items are the responsibility of | ||
+ | Documentation and which are the responsibility of Development.</p> | ||
+ | </td> | ||
+ | <td> | ||
+ | <p>Ben Gelernter, Rick Sapir</p> | ||
+ | </td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td> | ||
+ | <p>Review JPA topics to make sure all 2.2 and 2.3 features | ||
+ | are documented and reviewed. Update as needed.</p> | ||
+ | <p> </p> | ||
+ | </td> | ||
+ | <td> | ||
+ | <p>Ben Gelernter</p> | ||
+ | </td> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td> | ||
+ | <p>Create an Introduction/Overview section:</p> | ||
+ | <ul> | ||
+ | <li>If introductory information exists elsewhere (e.g., the | ||
+ | JPA intro section), move it to this section</li> | ||
+ | <li>Write any introductory information that is missing, | ||
+ | including cumentation will be maintained under the | ||
<i>Documentation Center</i> on the EclipseLink wiki at http://wiki.eclipse.org/EclipseLink/UserGuide">http://wiki.eclipse.org/EclipseLink/UserGuide. | <i>Documentation Center</i> on the EclipseLink wiki at http://wiki.eclipse.org/EclipseLink/UserGuide">http://wiki.eclipse.org/EclipseLink/UserGuide. | ||
</li> | </li> | ||
Line 412: | Line 541: | ||
<td> | <td> | ||
<p><b>MetadataSource support for PU Properties: </b>During | <p><b>MetadataSource support for PU Properties: </b>During | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Revision as of 10:46, 18 August 2011
Contents
Documentation Plan for EclipseLink 2.4
Please complete comments on this doc plan by Thursday, August 25.
Change Record
Date |
Author |
Change Record |
7/28/11 |
Ben Gelernter |
First draft |
8/11/11 |
Ben Gelernter |
Incorporated changes from doc manager review. |
8/17/11 |
Ben Gelernter |
Incorporated changes from doc team review |
This documentation plan describes how the documentation team will provide EclipseLink documentation for the EclipseLink; (EL) 2.4 release.
Schedule
Milestone |
Date |
Doc plan first draft |
8/10/11 |
Doc plan posted |
8/17/11 |
Doc plan comments due |
8/24/11 |
Final doc plan |
8/29/11 |
EclipseLink release 2.4 |
|
Audience
User |
Description |
Application Developers |
Developers who want to develop applications using any of the following technologies for persistence services:
Developers should be familiar with the concepts and programming practices of:
//REVIEWERS: Should this specify a Java version? which?// Assumed knowledge:
|
Administrator/Deployer |
Users who want to deploy and manage applications using the EclipseLink persistence technologies. Assumed knowledge: These users should be familiar with basic operations of the chosen Java EE compliant application server. //REVIEWERS: Is this correct simply to say "Java EE compliant app server"? Should it be something like "Java 5 EE compliant app server—some features are available only with Java 6 (or 7?) EE, and therefore users of those features should be familiar with those features in Java 6/7."? It may not even be important to specify. Please advise// |
Planned Documentation Deliverables
The Documentation team will document EclipseLink-specific features for:
- JPA (this is the highest priority)
- MOXy
- DBWS
The Documentation team will not document EIS, SDO, or any other "native" TopLink functionality (i.e., non-JPA such as ORM, OX, etc.)..
Documentation Design
The wiki topics will be handled as follows:
- All EclipseLink documentation will be maintained under the Documentation Center on the EclipseLink wiki at http://wiki.eclipse.org/EclipseLink/UserGuide">http://wiki.eclipse.org/EclipseLink/UserGuide.
- Versioning will be handled as follows:
- A note "New in EL 2.n" will be placed next to new topics in the TOCs, where n refers to the release when the feature was introduced. This is currently handled using template {{EclipseLink/NewIn2n}}.
- A note " New in version 2.n." will be added at the beginning of a topic documenting a new feature. This is currently handled using .
- If a new feature is handled in an existing topic and the topic changes more than 50%, the note " New in version 2.n." will be placed at the beginning of the topic or at the beginning of the appropriate section.
- Header and footers on the wiki page will contain no references to release numbers.
- If a feature is deprecated, a note will placed next to the documentation for the feature.
- Each topic will document one "feature." The term "feature" here is somewhat loose. In some cases, it is a single annotation. In some cases, the topic will document how to use multiple annotations together for a specific purpose, e.g., single-table multi=tenancy.
- These topics are more-or-less "reference" topics. That is, they document the primary APIs and XML used to implement the feature. There can be limited discussion about how to use the code to achieve the purpose of the feature, but we will not attempt to put the feature in a larger context or to fully document all related features.
- The JPA topics will primarily focus on using annotations, when they are available. For example, a topic may begin with something like, "Use the @Xyz annotation to…" and most or all examples and code snippets will show annotations. When the feature can also be coded using XML, the topic can discuss the XML (including a reference to the schema), but the documentation for XML will not be as extensive as the documentation for the annotation.
- Every topic will cross-reference:
- Any associated example provided by Development and located in the Samples section of the wiki.
- Any associated Javadoc. When an annotation is available, the reference will be to the annotation(s), not the "native API."
- The Documentation team will not document features that are not EclipseLink-specific. In particular, features that are documented in the specification for the underlying technology. For example features documented in the JSR-000317 JavaTM Persistence 2.0 specification will not be documented. However, anyone with permission to edit the wiki may add topics to the wiki. As time permits, the Documentation team may provide advice on the organization of topics. Any non-Documentation person adding topics is responsible for adding and maintaining the following:
- Previous and Next browse sequence links at the bottom of the page
- Links from the Table of Contents
- Links from the parent, or container, topic, if there is one. For example, the JPA documentation includes a "Weaving Topic" which introduces several weaving-related topics under it.
Note: A container topic should not contain only a list of links. Every topic must include at least an overview sentence. For example: "The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. Caching is discussed in the following topics:"
- Individual topics will not include cross references to the standard specifications (JPA, JAXB). There will be one overview topic (or an overview topic for each service) that will contain the link to the appropriate specification.
- If design documents (specs) are not available or do not contain enough source material (including examples), writers will file bugs against Development via BugZilla.
Tasks/Deliverables
The following tasks are not specifically associated with the EclipseLink 2.4 release but will be handled by the Documentation team during this period:
General
Task/Deliverable |
Writer |
||||||||||||||||||||
Identify topics in the JPA TOC that are documented in the JPA specification to clarify which existing items are the responsibility of Documentation and which are the responsibility of Development. |
Ben Gelernter, Rick Sapir |
||||||||||||||||||||
Review JPA topics to make sure all 2.2 and 2.3 features are documented and reviewed. Update as needed.
|
Ben Gelernter |
||||||||||||||||||||
Create an Introduction/Overview section:
Note: A container topic should not contain only a list of links. Every topic must include at least an overview sentence. For example: "The EclipseLink cache is an in-memory repository that stores recently read or written objects based on class and primary key values. Caching is discussed in the following topics:"
Tasks/DeliverablesThe following tasks are not specifically associated with the EclipseLink 2.4 release but will be handled by the Documentation team during this period: General
The following tables show the features that will be documented for EL 2.4. JPA Features
|