db-jdo-dev mailing list archives

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

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


Mime
View raw message