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