Mailing-List: contact river-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: river-dev@incubator.apache.org
Received-SPF: pass (herse.apache.org: local policy)
Message-ID: <45A36124.2010303@dcrdev.demon.co.uk>
Date: Tue, 09 Jan 2007 09:32:20 +0000
From: Dan Creswell <dan@dcrdev.demon.co.uk>
User-Agent: Thunderbird 1.5.0.9 (Macintosh/20061207)
MIME-Version: 1.0
To: river-dev@incubator.apache.org
Subject: Re: How to start from here?
References: <459A7EB9.8020301@cheiron.org>
 <45A24BBE.5010300@cheiron.org>	 <45A2598F.20308@Sun.COM>
 <45A25B72.4080907@cheiron.org>	 <45A25C64.2030404@Sun.COM>
	 <e202160f0701081150o2b1ebd7cp4414d369c517537c@mail.gmail.com>
	 <45A2C075.9080006@cheiron.org>
 <e202160f0701081602w64c1ec4eqc46f2d265d5e60a8@mail.gmail.com>
 <45A2DE91.4080208@wonderly.org> <45A355A9.8050108@cheiron.org>
In-Reply-To: <45A355A9.8050108@cheiron.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

Couple of comments inline but I'd like to suggest something of a
strategic option.  For me, at this stage, moving the specs around or
whatever is a detail (an important one) but I think we need a plan for
what we're trying to achieve overall - something like:

(1) Figure out what documentation we think we need overall

(2) Figure out what we have

(3) Figure out how (2) intersects with (1)

(4) Fill in the gaps

(5) Move it around 'til we like where it all lives

Now it might be y'all have answers to the above already in which case,
great - let's get 'em all out here.

Mark Brouwer wrote:
> Jeff, Gregg,
> 
> First thanks Jeff for not reopening the debate ;-) but to conclude it
> from my side. Here are my ideas and I think 'how to deal with
> documentation/specs' should be on the roadmap.
> 
> With both of you I agree that understanding the big picture ain't that
> easy and for that purpose an introductory walk-through would be the
> proper thing to have. Or a user/developer guide/tutorial that explains
> in lay-mans terms what it is all about.
> 

Indeed.

I suspect we might need some conceptual overview, high-level block diagrams.

Then a walk-through of common components like leases, exporters and stuff.

Then tutorials binding bits together - I'm not in favour of trying to do
everything in one tutorial example although the way Jini is that may be
too lofty of a goal.

> I can recall the Overture release had one, and the current JTSK has one
> for the new stuff as part of the "Jini(TM) Technology Starter Kit Overview"
> 
> But specs that are required for a reimplementation or that tell you what
> to expect in the not that less straightforward cases (which my mind
> always tend to look for) should IMO be where they belong and that is
> close as possible to the code that I have to my avail in my IDE.
>

Hmmm, knowing you as I do, I'm not surprised - me, I prefer the specs
separate and I cross ref into JavaDoc when I need to.

Ugh, it's a little too subjective for me.

> I see no problem in moving most of the Lease Specification
> http://java.sun.com/products/jini/2.1/doc/specs/html/lease-spec.html to
> the package documentation of net.jini.core.lease as long as people get
> linked there from an overview about leasing to that package.
> 
> As Gregg mentioned, the specification for javax.swing also links to the
> Swing tutorial. I don't see why we couldn't provide anchors to tutorial
> like information, as long as these tutorials are agnostic towards the
> framework (whether it is JTSK starter code, RIO, Seven, Harvester, etc.)
> and these tutorials are maintained at the River project. Marking those
> links as being no part of the spec is essential though.

Which just sounds way too complex to achieve.  Might be better not to
back-link like that?

Dan.