On Jul 6, 2007, at 4:44 AM, Aristedes Maniatis wrote:
Can Cayenne Classic Guide just be named "Cayenne Guide"? I think
the classic name makes it sound old and deprecated where it is
actually the most full featured way of using Cayenne.
You are right. But we still need to make a clear distinction between
two types of API's that Cayenne provides. "Classic vs. JPA" was self
explanatory to the existing users (not sure if it is to the new
users?). I guess we can call "classic" simply Cayenne API (vs. JPA
API provided by Cayenne). The distinction becomes a bit fuzzier, but
is still probably OK.
And would Cayenne ROP be clearer as "Cayenne Client"? Or do you
think that ROP is a well known term?
The ROP name was a product of a discussion some time ago:
http://objectstyle.org/cayenne/lists/cayenne-devel/2005/11/0024.html
I'd like to have a shorter definition than "Remote Object
Persistence", but I still feel like "Client" is not reflecting the
meaning of this technology.
I still like the idea of (in the future) having only one guide and
continuing to maintain it rather than forking the guide for every
release. That way documentation improvements are useful and
accessible to users of all versions. We'd just need to clearly mark
pages or sections with "introduced in 3.0".
IIRC we tried it in the past. The problem is mostly the slight
conceptual shift across the versions, i.e. we do not simply introduce
*new* things, we also factor out old stuff ... or start calling it a
different name. E.g. I'd like to emphasize ObjectContext interface
some more now, as opposed to its concrete (and still most common)
implementation DataContext. To a 1.1 user this would make no sense.
So while we should fork as rarely as possible, I don't think it is
realistic to avoid it all together.
Let us know if there is anything we can do to help with your
documentation work.
Here is an incomplete list of topics off the top of my head (we do
not necessarily need to finish all of them for M1) :
* Fill in missing information on "What's new" page
* New caching features
* ObjectContext interface
* Logging (removal of log4j)
* Cayenne agent and POJO's
* JPA tutorial
If you want to grab any of those, please send a note to the list.
Also, I noticed that Confluence has now (in an unreleased beta
version) got ordered child pages. No more alphabetic listing of
children. That will be very helpful to us when Apache gets that
release installed.
And that's one day after I fixed the ordering in the docs export
plugin! :-)
https://issues.apache.org/cayenne/browse/CAY-822
Andrus
