db-jdo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andy Jefferson (JIRA)" <j...@apache.org>
Subject [jira] Commented: (JDO-537) Upgrade Apache JDO site to encompass user-level documentation/guides etc
Date Tue, 02 Oct 2007 13:11:50 GMT

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


Mime
View raw message