Mailing-List: contact lucy-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: lucy-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: local policy)
Date: Wed, 13 Apr 2011 20:20:06 -0700
From: Marvin Humphrey <marvin@rectangular.com>
To: lucy-dev@incubator.apache.org
Message-ID: <20110414032006.GA31365@rectangular.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.5.18 (2008-05-17)
Subject: [lucy-dev] URL design for website API docs

Greets,

Before we release 0.1.0, we should prepare an HTML export of Lucy's API
documentation for our website.  As with any web publication, we should think
hard about URL structure before we publish.

We need to take the following factors into consideration:

    * Version numbers.
    * Host languages.
    * API-unstable mainline vs. stable forks.
    * SEO.
    * Length/ease-of-typing.
    * The possibility that lucy.apache.org might host sub-projects someday.

In anticipation of Lucy's graduation from the Incubator :) I'll specify these
urls with a root of <http://lucy.apache.org/> rather than
<http://incubator.apache.org/lucy>.

I propose the following URL scheme:

    http://lucy.apache.org/docs/               <-- homepage
    http://lucy.apache.org/docs/perl/          <-- TOC for latest Perl bindings
    http://lucy.apache.org/docs/ruby/          <-- TOC for latest Ruby bindings
    ...

At some future date, we should begin archiving the docs for each release:

    http://lucy.apache.org/docs/X.Y.Z/
    http://lucy.apache.org/docs/X.Y.Z/perl/
    http://lucy.apache.org/docs/X.Y.Z/ruby/
    ...

We should hold off on archiving for now, though, so that the primary location
has a chance to establish itself as authoritative.

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

As we add host language bindings, we will get a increasing proliferation of
documentation pages and there will be a lot of apparent duplication.  That's
OK, because it's in keeping with our emphasis on idiomatic bindings to provide
documentation which is customized for each host.  We should not have any
binding docs which refer people to the C documentation -- the docs for each
binding should be authoritative and complete.

The docs homepage needs to provide prominent links to the binding TOCs for the
latest API-unstable release.

    http://lucy.apache.org/docs/perl/
    http://lucy.apache.org/docs/ruby/
    ...

Once we fork a stable release, the docs homepage should also link to its
archived documentation as well:

    http://lucy.apache.org/docs/1.0.0/perl/
    http://lucy.apache.org/docs/1.0.0/ruby/
    ...

Stable fork documentation should go straight to the archive -- I don't believe
that establishing a "latest stable" directory is either necessary or desirable.

Ideally, performing the following web searches will yield the following top results:

    lucy indexer
        http://lucy.apache.org/docs/perl/Lucy/Index/Indexer.html
    lucy1 indexer
        http://lucy.apache.org/docs/1.0.0/perl/Lucy1/Index/Indexer.html

The Perl documentation for Lucy will get established earliest, so it will
probably win out in searches for some time to come.  However, hopefully adding
the name of another binding language will suffice to bring up the right page.

    lucy indexer ruby
        http://lucy.apache.org/docs/ruby/Lucy/Index/Indexer.html
    lucy1 indexer ruby
        http://lucy.apache.org/docs/1.0.0/ruby/Lucy1/Index/Indexer.html

I don't think we need to worry about URL collisions between the API-unstable
trunk and the stable forks ("Lucy1", "Lucy2", ...).  Under our current plan,
"Lucy" will always be 0.Y.Z, "Lucy1" will always be 1.Y.Z, etc. -- so there
shouldn't be any conflicts.

If we ever publish subprojects under the Lucy aegis, I expect that they will
end up in their own subdirectories which replicate the structure of the Lucy
root dir.

    http://lucy.apache.org/charmonizer/docs/X.Y.Z/

So long as we don't publish a subproject named "docs" we should be fine. :)

Marvin Humphrey