You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-dev@db.apache.org by "Andy Jefferson (JIRA)" <ji...@apache.org> on 2007/09/29 19:44:50 UTC
[jira] Created: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Upgrade Apache JDO site to encompass user-level documentation/guides etc
------------------------------------------------------------------------
Key: JDO-537
URL: https://issues.apache.org/jira/browse/JDO-537
Project: JDO
Issue Type: Improvement
Components: site and infrastructure
Reporter: Andy Jefferson
Assignee: Andy Jefferson
Fix For: JDO 2 maintenance release 1
The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
http://www.jpox.org/docs/jdo/jdo_overview.html
and they could be moved across.
The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
http://www.jpox.org/apachejdo/index.html
This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
I'd anticipate adding the following side menu groups, but others may have better ideas
* Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
* Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Posted by "Craig Russell (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/JDO-537?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12537106 ]
Craig Russell commented on JDO-537:
-----------------------------------
Many thanks, Andy, for doing all this work. The site is much better for it.
> Upgrade Apache JDO site to encompass user-level documentation/guides etc
> ------------------------------------------------------------------------
>
> Key: JDO-537
> URL: https://issues.apache.org/jira/browse/JDO-537
> Project: JDO
> Issue Type: Improvement
> Components: site and infrastructure
> Reporter: Andy Jefferson
> Assignee: Andy Jefferson
> Fix For: JDO 2 maintenance release 1
>
> Attachments: xdocs.zip
>
>
> The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
> http://www.jpox.org/docs/jdo/jdo_overview.html
> and they could be moved across.
> The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
> http://www.jpox.org/apachejdo/index.html
> This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
> I'd anticipate adding the following side menu groups, but others may have better ideas
> * Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
> * Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Posted by "Andy Jefferson (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/JDO-537?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12532086 ]
Andy Jefferson commented on JDO-537:
------------------------------------
Apache JDO logo moved to left hand side.
Docs split between User and Implementor.
Majority of JPOX docs migrated.
> Upgrade Apache JDO site to encompass user-level documentation/guides etc
> ------------------------------------------------------------------------
>
> Key: JDO-537
> URL: https://issues.apache.org/jira/browse/JDO-537
> Project: JDO
> Issue Type: Improvement
> Components: site and infrastructure
> Reporter: Andy Jefferson
> Assignee: Andy Jefferson
> Fix For: JDO 2 maintenance release 1
>
> Attachments: xdocs.zip
>
>
> The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
> http://www.jpox.org/docs/jdo/jdo_overview.html
> and they could be moved across.
> The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
> http://www.jpox.org/apachejdo/index.html
> This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
> I'd anticipate adding the following side menu groups, but others may have better ideas
> * Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
> * Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Resolved: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Posted by "Andy Jefferson (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/JDO-537?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Andy Jefferson resolved JDO-537.
--------------------------------
Resolution: Fixed
All planned docs to be migrated are now there. The "Why JDO" doc has been updated subsequent to comments. Any further doc changes can be handled by separate JIRAs
> Upgrade Apache JDO site to encompass user-level documentation/guides etc
> ------------------------------------------------------------------------
>
> Key: JDO-537
> URL: https://issues.apache.org/jira/browse/JDO-537
> Project: JDO
> Issue Type: Improvement
> Components: site and infrastructure
> Reporter: Andy Jefferson
> Assignee: Andy Jefferson
> Fix For: JDO 2 maintenance release 1
>
> Attachments: xdocs.zip
>
>
> The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
> http://www.jpox.org/docs/jdo/jdo_overview.html
> and they could be moved across.
> The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
> http://www.jpox.org/apachejdo/index.html
> This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
> I'd anticipate adding the following side menu groups, but others may have better ideas
> * Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
> * Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Posted by "Michelle Caisse (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/JDO-537?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12531634 ]
Michelle Caisse commented on JDO-537:
-------------------------------------
About deployment - db.apache.org uses maven and their process is to do "maven site:deploy" which deploys the site to the staging server. However, it only works if you have uploaded an ssh key to the server, which IMO is an annoyance. I prefer the current process, which has more manual steps, but works. Presumably we could create a maven goal to copy to docs, then carry on as usual.
> Upgrade Apache JDO site to encompass user-level documentation/guides etc
> ------------------------------------------------------------------------
>
> Key: JDO-537
> URL: https://issues.apache.org/jira/browse/JDO-537
> Project: JDO
> Issue Type: Improvement
> Components: site and infrastructure
> Reporter: Andy Jefferson
> Assignee: Andy Jefferson
> Fix For: JDO 2 maintenance release 1
>
> Attachments: xdocs.zip
>
>
> The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
> http://www.jpox.org/docs/jdo/jdo_overview.html
> and they could be moved across.
> The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
> http://www.jpox.org/apachejdo/index.html
> This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
> I'd anticipate adding the following side menu groups, but others may have better ideas
> * Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
> * Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Posted by "Michelle Caisse (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/JDO-537?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12531641 ]
Michelle Caisse commented on JDO-537:
-------------------------------------
The pages look quite nice. The only design change I would make is to do something about the big empty space at the top. Probably not possible, but it might look okay to put the logo on the left over the navbar and start the page text at the top of the page. Alternatively, we can make a banner with "Java Data Objects" in large font.
It's odd that the logo links to each page that it is on. What's the point? I think that it should link to the home page.
Comments on the new Documentation entries: I'd like to see Tutorials subsumed under Documentation. Possibly we should rename Documentation to User Documentation and have another section called Information for Implementors with the specs and TCK page. I would like to separate information for implementors and users in some way. I'd like to have fewer top-level entries under Documentation. Maybe Persistence Technologies Compared, JDO API, Metadata, Tutorials, and Glossary at the top level, opening up to the individual docs.
I suggest that we take the changes in steps. First, switch to the new design and support technology with minimal changes to the site, then add new docs in steps as we get a chance to review them.
Thanks for doing this, Andy.
> Upgrade Apache JDO site to encompass user-level documentation/guides etc
> ------------------------------------------------------------------------
>
> Key: JDO-537
> URL: https://issues.apache.org/jira/browse/JDO-537
> Project: JDO
> Issue Type: Improvement
> Components: site and infrastructure
> Reporter: Andy Jefferson
> Assignee: Andy Jefferson
> Fix For: JDO 2 maintenance release 1
>
> Attachments: xdocs.zip
>
>
> The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
> http://www.jpox.org/docs/jdo/jdo_overview.html
> and they could be moved across.
> The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
> http://www.jpox.org/apachejdo/index.html
> This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
> I'd anticipate adding the following side menu groups, but others may have better ideas
> * Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
> * Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Posted by "Andy Jefferson (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/JDO-537?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Andy Jefferson updated JDO-537:
-------------------------------
Attachment: xdocs.zip
Current working set of files for "/jdo/site/". Note that the previous "lib" and "build.xml" aren't needed with this process. Simply type "maven site" and the docs are built under target/docs. Still need to then copy them into "docs" for consistency with the current process of putting the site onto Apache
> Upgrade Apache JDO site to encompass user-level documentation/guides etc
> ------------------------------------------------------------------------
>
> Key: JDO-537
> URL: https://issues.apache.org/jira/browse/JDO-537
> Project: JDO
> Issue Type: Improvement
> Components: site and infrastructure
> Reporter: Andy Jefferson
> Assignee: Andy Jefferson
> Fix For: JDO 2 maintenance release 1
>
> Attachments: xdocs.zip
>
>
> The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
> http://www.jpox.org/docs/jdo/jdo_overview.html
> and they could be moved across.
> The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
> http://www.jpox.org/apachejdo/index.html
> This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
> I'd anticipate adding the following side menu groups, but others may have better ideas
> * Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
> * Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (JDO-537) Upgrade Apache JDO site to encompass
user-level documentation/guides etc
Posted by "Andy Jefferson (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/JDO-537?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12531786 ]
Andy Jefferson commented on JDO-537:
------------------------------------
Thanks for your comments Michelle.
1. Deployment. I added a Maven1 goal "savesite" that does the copy from target/docs to docs, so the deploy uses the existing mechanism (and I've never used maven site:deploy anyway so have no issue with using what you have there).
2. Logo link, now goes to "http://db.apache.org/jdo".
3. Space on the header. We can put whatever you want there. See the JPOX docs, where we have a banner. This is defined in the xdocs/site.jsl file, the block that starts <div id="banner">. Some sites put the parent Apache project (e.g http://db.apache.org) but in this case I see little point since that is not a project as such, just a storage container with no defined purpose. Open to suggestions ... "Java Data Objects" image of some form if anyone feels artistic ;-)
4. Switch to new design, so I've checked in the following
Sending /usr/local/tck/jdo/site/HOWTO
Adding /usr/local/tck/jdo/site/maven.xml
Adding /usr/local/tck/jdo/site/project.properties
Adding /usr/local/tck/jdo/site/project.xml
Adding /usr/local/tck/jdo/site/xdocs/enhancement.xml
Adding /usr/local/tck/jdo/site/xdocs/exceptions.xml
Adding /usr/local/tck/jdo/site/xdocs/glossary.xml
Sending /usr/local/tck/jdo/site/xdocs/impls.xml
Adding /usr/local/tck/jdo/site/xdocs/jdo_dtd.xml
Adding /usr/local/tck/jdo/site/xdocs/jdo_v_jpa.xml
Adding /usr/local/tck/jdo/site/xdocs/jdo_v_jpa_orm.xml
Adding /usr/local/tck/jdo/site/xdocs/jdohelper.xml
Adding /usr/local/tck/jdo/site/xdocs/jdoquery_dtd.xml
Adding /usr/local/tck/jdo/site/xdocs/navigation.xml
Adding /usr/local/tck/jdo/site/xdocs/orm_dtd.xml
Adding /usr/local/tck/jdo/site/xdocs/site.jsl
Adding /usr/local/tck/jdo/site/xdocs/specifications.xml
Adding /usr/local/tck/jdo/site/xdocs/style
Adding /usr/local/tck/jdo/site/xdocs/style/maven-base.css
Adding /usr/local/tck/jdo/site/xdocs/style/maven-classic.css
Adding /usr/local/tck/jdo/site/xdocs/style/maven-theme.css
Adding /usr/local/tck/jdo/site/xdocs/style/print.css
Adding /usr/local/tck/jdo/site/xdocs/tutorials
Adding /usr/local/tck/jdo/site/xdocs/tutorials/replication.xml
Adding /usr/local/tck/jdo/site/xdocs/why_jdo.xml
(and the associated docs files)
Transmitting file data ...
Committed revision 581216.
So there are a small number of new docs added. Feel free to update as required. I've updated the HOWTO to describe the places needing changes when adding docs or changing the navigation.
5. The existing build.xml and lib files are still present currently, so we have an easy way of back-comparing, but need removing before closure of this JIRA.
> Upgrade Apache JDO site to encompass user-level documentation/guides etc
> ------------------------------------------------------------------------
>
> Key: JDO-537
> URL: https://issues.apache.org/jira/browse/JDO-537
> Project: JDO
> Issue Type: Improvement
> Components: site and infrastructure
> Reporter: Andy Jefferson
> Assignee: Andy Jefferson
> Fix For: JDO 2 maintenance release 1
>
> Attachments: xdocs.zip
>
>
> The Apache JDO site is good as far as it goes, but is typically at a developer level. The vast majority of users don't read the JDO specification, and certainly not in any detail. It would benefit from a revamp to take on user-level docs describing basic JDO terminology such as PersistenceManager, PersistenceManagerFactory, JDOQL, Extents etc etc. In addition some simple worked examples would aid uptake. The JPOX site already has a selection of such docs at
> http://www.jpox.org/docs/jdo/jdo_overview.html
> and they could be moved across.
> The current site is generated using Anakia, but would likely be more extensible and cleaner using Maven1 site/xdoc plugins. As a demonstration of this, there is an initial Maven1 version of the Apache JDO site at
> http://www.jpox.org/apachejdo/index.html
> This demo has had very little configuration, and is located there temporarily to allow feedback, and will be removed in the future. Maven1 site/xdoc allows "navigation.xml" (to define the side navigation), "site.jsl" (to define the velocity process of putting together top, side, body and bottom areas on each page), and 3 CSS files to control styling, fonts and such. The side menu can benefit from submenus with expand/collapse to aid display of large amounts of content.
> I'd anticipate adding the following side menu groups, but others may have better ideas
> * Documentation - with pages for different JDO concepts PM, PMF, JDOQL, Extent, etc
> * Tutorials - very simple worked examples, things like 1-1, or replication, or how to have an M-N with attributes
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.