Jini documentation [Was: Re: How to start from here?]

[Mark Brouwer <ma...@cheiron.org>]

I move to a different subject because I think it is better if we have
each roadmap item in a separate thread.

Dan Creswell wrote:
> 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.

It is important to talk about what kind of documentation we need and
something we should get rolling, but to me it is not a priority and as
such also not something I expect to spend much time on.

The only thing I find important at this stage is whether we are going to
follow a common rule about how we are going to spec and keep that
uniform. E.g. if there is maintenance on the lookup and discovery
specification are we going to move that over in a fashion comparable
with the newer specs or are we going to defrost the current HTML specs
to the minimum that we can alter a few paragraphs.

>> 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.

Can't resist, why should one be surprised ;-) I think it is completely
logical to try to find the semantics of a method at the method level.

Going to a spec to have to find out whether a lease duration can be
negative or even zero should be something the javadoc for the
'duration' argument at the method level should tell me, and the
IllegalArgumentException should make it even more obvious.

I've seen too many bugs lingering in code that were there because the
distance between code and semantics was too far apart. And often I was
not in the position to spank those people responsible for I had to admit
knowing the semantics was a job too much effort for the 21 century man.
-- 
Mark

Re: Jini documentation [Was: Re: How to start from here?]

[Mark Brouwer <ma...@cheiron.org>]

Brian Murphy wrote:
> On 1/9/07, Dan Creswell <da...@dcrdev.demon.co.uk> wrote:
> r
>> I must admit, I'm a little concerned about all these rules we seem to
>> want to put in place up front in the absence of experience in this new
>> environment.
> 
> +1

So far I think the request for rules is not that high as one might
conclude from the remark in Dan's posting, but I admit I was the first
one to use that word in the documentation mail. Other than the usage of
JIRA I can't come up with real request for rules. Phil was so kind to
draft a patch and not that many people expressed their opinion about it,
why I ask myself already for a few days.

I guess all of us are eagerly waiting for the initial source drop to get
'coding', but before it is there I don't think it is harmful if we share
opinions about what kind of guidelines we think might be necessary, or
that from adhoc decisions we expect to have them emerge.

A guideline can be modified, no need to carve them in stone, but I think
for people looking to participate it is handy when there is something
that reflects the how we think we want to work. There are engineering
practices used that resulted in the excellent quality of the JTSK and to
the fine standards/specifications we have today. I don't know to what
extend some of the processes used by the Jini team scale in an ASF
project, or even if it is possible to maintain some of them at all, or
whether we should want, but I think at least we should discuss these
things here.

Another example: split or merge? On the Internet I hear talk about
repackaging of the JTSK, I expressed my opinion (although very shallow)
as did Bob and Gregg, everyone else seems to be rather silent on this
matter here. We can change things later, but we know how inertia works,
IMHO it would be nice to have at least some of this discussion before
the ServiceUI and JTSK are checked-in.

Please, please, please, don't read this as an attack on anyone, but so
far I can't say there are many opinions expressed.
-- 
Mark

Re: Jini documentation [Was: Re: How to start from here?]

[Brian Murphy <bt...@gmail.com>]

On 1/9/07, Dan Creswell <da...@dcrdev.demon.co.uk> wrote:

> I must admit, I'm a little concerned about all these rules we seem to
> want to put in place up front in the absence of experience in this new
> environment.

+1

Brian

Re: Jini documentation [Was: Re: How to start from here?]

[Mark Brouwer <ma...@cheiron.org>]

[Sorry, I intended to start a new thread, but failed miserable for
proper email readers]

Dan Creswell wrote:

> And that's all fine but:
> 
> (1)	Realize that all your good work elsewhere mightn't get
> recognized/used if we don't look seriously at the issue.  After all, no
> user community, no interest in all the good stuff Mark has done.

I believe I said it to be important, but with the work up on my sleeves
I must make priorities too. Personally I think there is enough good
documentation about the concepts of Jini, with regard to the hard stuff
I think most people should be shielded of that, or rather unaware, or it
is that hard they have the dig the specs anywhere, but this is another
topic I guess.

But believe me, I won't be a roadblock when others want to go ahead,
only when it is decided javadoc is the wrong place for specifications I
will foam with rage ;-)

> (2)	The stuff that you do elsewhere can make it more difficult to get
> users through the door if it's the wrong choice for them whilst being
> the right choice for you.

That might be very well the case, but I always have great difficulties
valuing that against my own beliefs.

> And I'd say let's get ourselves up and running and worry about this
> issue when we hit it.  There's lots of other stuff that needs doing as well.

I've pipelined a few things that will hit this issue, so for me it is
imminent. But for me it was a roadmap issue not one thing we should
decide upon now.
-- 
Mark

Re: Jini documentation [Was: Re: How to start from here?]

[Dan Creswell <da...@dcrdev.demon.co.uk>]

Mark Brouwer wrote:
> I move to a different subject because I think it is better if we have
> each roadmap item in a separate thread.
> 
> Dan Creswell wrote:
>> 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.
> 
> It is important to talk about what kind of documentation we need and
> something we should get rolling, but to me it is not a priority and as
> such also not something I expect to spend much time on.
> 

And that's all fine but:

(1)	Realize that all your good work elsewhere mightn't get
recognized/used if we don't look seriously at the issue.  After all, no
user community, no interest in all the good stuff Mark has done.

(2)	The stuff that you do elsewhere can make it more difficult to get
users through the door if it's the wrong choice for them whilst being
the right choice for you.

> The only thing I find important at this stage is whether we are going to
> follow a common rule about how we are going to spec and keep that
> uniform. E.g. if there is maintenance on the lookup and discovery
> specification are we going to move that over in a fashion comparable
> with the newer specs or are we going to defrost the current HTML specs
> to the minimum that we can alter a few paragraphs.
> 

And I'd say let's get ourselves up and running and worry about this
issue when we hit it.  There's lots of other stuff that needs doing as well.

I must admit, I'm a little concerned about all these rules we seem to
want to put in place up front in the absence of experience in this new
environment.  It feels somewhat like trying to write specs before we've
had experience with solving an issue which is an oft-cited failing of
such things as WS-*

Dan.