cayenne-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrus Adamchik <and...@objectstyle.org>
Subject Re: Website CMS
Date Thu, 08 Nov 2012 07:56:11 GMT
On Nov 8, 2012, at 3:14 AM, Aristedes Maniatis <ari@maniatis.org> wrote:
>> Today loaded 3.1 javadocs and docbook HTML to the cms site. We have a total of 4
independent books in 3.1 (will probably refactor the whole docbook structure soon to make
them easier to manipulate). Manually copying the folders wasn't too bad. The worst part was
"git svn dcommit" after a Javadocs dump. But never the less it worked.
>> 
>> Notice the new docs structure. I wanted the subfolders to logically follow dropdown
menus, so instead of calling it /doc31/, I went with /doc/3_1/ :
>> 
>> http://cayenne.staging.apache.org/doc/3_1/index.html
> 
> Not sure how changing the path syntax helps. If you really want to do that we'll need
redirects from all the old simpler URLs to the new structure.
> Remember that people will end up in doc pages from a google search and may just change
the URL to go to a different version.

I didn't touch 1.2, 2.0, 3.0 layout. So no need for redirects. I strongly support the notion
that we shouldn't be changing the existing well-publicized URLs without a cause. And if we
do, always provide a 301 redirect (see "content/.htaccess"). But this is not the case here.


The new scheme starts with 3.1 release. Among other things the new CMS freed us from the directory
and file naming imposed by Confluence Autoexport, so I figured the URLs might follow the menu
hierarchy for the docs. Also "unflattening" the top directory structure seems like a good
thing for our own sanity.

> I also suggest a redirect
> 
> /doc/latest/  -->  /doc/3.1/
> 
> That makes it easier to refer people to the docs and for the links in mailing list archives
to remain pointing to the current docs.

I've been thinking about this for some time. A "latest" symlink is both good and bad. The
positive is that it creates a perception of a single set of docs. The negative is that we
do have multiple versions of the docs after all and it is not always clear what "latest" means
on any given day and associating "latest" with this moving target is not always such a clear
cut. As Cayenne accumulates more major releases, I feel like using explicit versioning everywhere
will save us and users from more trouble.

Taking your example, links in mailing list archives would actually work better with no "latest"
symlink. Consider that some docs go away occasionally (e.g. dataviews are no longer in Cayenne,
jpa, etc.). So this example seems to validate the version-aware URL approach.

>> Ari, any word on publishing our staging to the live site?
> 
> Yes, spoke to infra and created a ticket a few days ago. It is on their list.

Awesome.

Andrus

Mime
View raw message