Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [eclipselink-dev] EclipseLink 2.1 Documentation Proposal
The plan is to host the individual XML in SVN.
 
-R
-----Original Message-----
From: Michael Norman
Sent: Thursday, December 17, 2009 2:23 PM
To: Dev mailing list for Eclipse Persistence Services
Subject: Re: [eclipselink-dev] EclipseLink 2.1 Documentation Proposal


I agree that the wiki is more community friendly; however, the wiki software run by the Eclipse Foundation
(MediaWiki, same as Wikipedia - see http://www.wikimatrix.org for a list) is not optimal for product document
preparation: per-page size-restrictions, lack of inline diagramming tools, image attachments stored in 'flat' namespace
(i.e. if your image is called 'foo.gif' and someone else has already uploaded an image with that name, then your gif
will over-write the other if you don't pay attention!) and my favourite challenge - editing through a very busy firewall!!

Am I correct that we would use OpenOffice to produce the DocBook files? Where would the output be hosted?

---
Mike Norman

James Sutherland wrote:

Personally, I prefer the wiki format to a document, as it is more community friendly, and better integrated with the web, easier to review and update.

<!--[if !supportEmptyParas]--> <!--[endif]-->

<!--[if !supportEmptyParas]--> <!--[endif]-->

-----Original Message-----
From: Douglas Clarke
Sent: Thursday, December 17, 2009 12:17 PM
To: Eclipselink-Dev (E-mail); Eclipselink-Users (E-mail)
Subject: [eclipselink-dev] EclipseLink 2.1 Documentation Proposal

<!--[if !supportEmptyParas]--> <!--[endif]-->

EclipseLink Committers and Users,

Based on community feedback we have decided that we should make some efforts to improve the EclipseLink User Guide (ELUG) currently hosted on the Eclipse Wiki @ http://wiki.eclipse.org/EclipseLink/UserGuide. This initial ELUG was based on the contribution of the original Oracle TopLink manual(s) converted directly into wiki content. While this was a great way to get started it does have some usability issues and contains older content that does not align with our current development efforts.

Our goal is address the requirements we have identified at http://wiki.eclipse.org/EclipseLink/Development/Documentation/Requirements.

Our proposed solution is to author new user guides using an open XML based content format with the content managed within the EclipseLink SVN repository. The format will be DocBook XML files. We are looking for feedback on the approach as well as recommendations, suggestions, best practice experience and of course contributors.

The first guide we propose creating is for EclipseLink JPA. We have started brain-storming a table of contents here: http://wiki.eclipse.org/EclipseLink/Development/Documentation/JPA

Please get involved with this important process and provide your feedback on the eclispelink-dev@xxxxxxxxxxx mailing list or on the discussion pages for the provided requirement and JPA guide wiki pages.

Cheers,

Doug


_______________________________________________
eclipselink-dev mailing list
eclipselink-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipselink-dev

Back to the top