lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <mar...@rectangular.com>
Subject Re: [lucy-dev] URL design for website API docs
Date Fri, 15 Apr 2011 21:40:00 GMT
On Fri, Apr 15, 2011 at 01:22:20PM -0700, Nathan Kurz wrote:
> > To find the documentation for Indexer's Perl bindings in the latest
> > API-unstable Lucy release, you would look here:
> >
> >    http://lucy.apache.org/lucy/docs/perl/Lucy/Index/Indexer.html
> >
> > Here's where you'd find the analogous page for archived release Lucy X.Y.Z:
> >
> >    http://lucy.apache.org/lucy/docs/X.Y.Z/perl/Lucy/Index/Indexer.html
> 
> Was it intentional that these are "/lucy/docs" and the paths above are "/docs"?
 
No, that was a typo. :(

I'd originally worked out this scheme using http://incubator.apache.org/lucy
as the base URL.  I messed up when editing, neglecting to remove the "/lucy"
for those two URLs.  Here's what they should have looked like:

  http://lucy.apache.org/docs/perl/Lucy/Index/Indexer.html
  http://lucy.apache.org/docs/X.Y.Z/perl/Lucy/Index/Indexer.html

> While it's redundant to have 'lucy' repeated in the domain and path,
> it might make life easier.   For example, when one migrates from
> incubator.apache.org to lucy.apache.org, all absolute path links will
> still work.  And if one ever migrates again, it should just be a drop
> in. One could mostly solve this by sticking with directory relative
> URL's, but with the multiple versions one will probably want some
> absolutes.

Migrating from the incubator to the lucy.apache.org top-level location is a
one-time cost.  It's more important to have our primary doc URLs be shorter
going forward.

> So I'm fine with either, but would lean to leaving 'lucy' in the path.

I have a reasonably strong preference for leaving that extra "/lucy" off.  I
thought hard about how to make those URLs as short as possible!  Consider this
change:

    http://www.rectangular.com/kinosearch/docs/devel/KinoSearch/Search/IndexSearcher.html
    http://lucy.apache.org/docs/perl/Lucy/Search/IndexSearcher.html

Even with the host language in there, we're still way shorter than we used to
be.

>  It also keeps things clear if/when subprojects are added.  But it
> doesn't seem worth too much worry.
> 
> Rest seems good.

Groovy, thanks for the review!

Marvin Humphrey



Mime
View raw message