On Sep 3, 2006, at 3:32 PM, Borut Bolčina wrote:
By the way - I think Cayenne deserves better web page (a more
consolidated
look). There should be no old news on the front page. Old news is
much worse
than no news at all. There should be link to tutorials on the front
page.
The navigation is confusing - there should be no Show Children link in
Confluence documentation. A link to PDF documentation would also
get newbies
up to speed more quickly, not to mention the book ;-) If Cayenne is
to be
more recognized, good technology is not enough, but I am sure we
all know
that. Now, how can I help?
You make a number of good points and help with the website and the
docs is greatly appreciated.
Note that we have two distinct systems here - a website generated
from XML sources and a Confluence wiki. Site contributions can be
made as patches via Jira. Site XML sources are available here:
https://svn.apache.org/repos/asf/incubator/cayenne/site/
With Confluence this is a bit more tricky. There are a number of issues.
Re: Child Linking - essentially we have an (imperfect) solution that
works both online and allows us to do an export to the offline docs.
Currently each documentation page has a hidden "excerpt" tag, and
there is a SOAP client that exports the pages to HTML and processes
the "excerpt" tag to build the table of contents:
http://cwiki.apache.org/CAY/documentation-guidelines.html
https://svn.apache.org/repos/asf/incubator/cayenne/main/trunk/other/
cayenne-build-tools/
We can either duplicate this tag in a visible block on each page with
children, so that they are easy to navigate. Or replace it entirely
with a visible tag and change the exporter code to use the new tag
instead of "excerpt". Cris Daniluk who wrote the original exporter
may have more insight into that (although he hasn't been posting to
the list for some time ... not sure if he reads this).
Re: PDF - we can generate PDF from Confluence already. The problem is
that it is unstructured (IIRC pages are listed alphabetically or
something). If you can help to extend the export client to build
readable PDF it would be very helpful.
Cheers,
Andrus
