On Nov 8, 2012, at 3:14 AM, Aristedes Maniatis <[email protected]> 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
