[sldev] [PROTOCOL] Protocol Documentation

[Rob Lanphier]

Hi Zha,

I'll actually go further:  we expect, as we migrate to the next
generation architecture, that the wiki hosted specifications will become
the default way of documenting and understanding the system at the
protocol and component interaction level.  As subsystems and protocols
stabilize, that documentation will likely transition toward an
architecture document with a LOT of references to standards published by
internationally recognized standards bodies, because one of three things
happens:
1)  We've transitioned key architectural components toward using
existing (or "to be existing" standards)
2)  We've actually submitted material from the wiki to an existing
standards body for refinement and standardization
3)  We've helped form a new standards body to submit material to, we've
submitted material developed on the wiki, and as a result of our
collaboration with others, that standards body gains enough gravity,
momentum, and credibility to be internationally recognized as a rightful
publisher of standards.

We're not at all sure #3 above is necessary, but I put that in there for
the sake of completeness, because we haven't ruled it out.

Since there's no guarantee that our current paying customers are going
to have the patience to stick with us while we work on ornate, detailed
specifications of our system as it exists today, we're going to have to
figure out how to do all of this as a by-product of getting our
respective day jobs done.  So, that's why your help (where "you" is
"you, dear reader of sldev") is greatly appreciated.

Thanks
Rob

On 10/3/07 10:56 AM, Zha Ewry wrote:
> Rob, thanks for that very clear statement. Zero was very clear, and
> you were, during the kick off a few weeks back, that Linden Labs has
> to balance several things at once. Linden has to grow and evolve the
> existing code base, while working towards the new design. A lot of
> what people are going to want, in an open, extensible specification
> won't much help Linden with their short term goals. That's fine, and 
> I, and hopefully other particpants here understand that having Linden
> blow up in the short term, in service of the long term is a bad thing 
> By the same token, I think, and hope that Linden understands that
> longer term, they need to address these issues.
>
> Hopefully, most of us aren't asking Linden to do the impossible, all
> at once. But.. I think we are stating, very clearly, that for formal
> specifications, we need more than source code. As you've observed, the
> AWG is the place a lot of that is going to happen. That's entirely
> sane, to me.
>
> A clear statement of direction that says "We expect, as we migrate to
> the next generation architecture, that the wiki hosted specifications
> will become the default way of documenting and understanding the
> system at the protocol and component interaction level" or words to
> that effect, would be very nice ;-)
>
> I don't expect an endeavor of this sort to be easy, painless, or move
> in a straight line. I do hope, that over time, we'll all end up on the
> same page, as to what we, as various players in the process need to do
> collectively, to get to a point where we can say "Look, here's a fully
> openly developed specification.
> you can read it and implement it. Here's Linden Lab's implementation
> of the spec, and here's the OpenSim one, and look, they work together."
>
> - Zha
>
>
> On 10/3/07, *Rob Lanphier* <robla at lindenlab.com
> <mailto:robla at lindenlab.com>> wrote:
>
>     Hi Argent,
>
>     Comment below:
>
>     On 10/3/07 8:08 AM, Argent Stonecutter wrote:
>     > I'm not knocking Linden Labs here. Open Sourcing the client was an
>     > amazingly cool thing, it was really courageous of them to do
>     that, and
>     > I'm not criticizing them where they haven't gone further by any
>     means.
>     > I'm just trying to promote another kind of openness... one that's as
>     > old a part of the software industry as Open Source and just as
>     > important... and arguing that it needs some kind of commitment
>     from LL
>     > that they don't seem to have made:
>     >
>     > * LL: we can't log every change, it would be cluttered and
>     irrelevant
>     > * LL: the source code is very clear on how all of this works
>     > * LL: it [the code] is very clear documentation
>     > * LL: so this whole discussion about documenting the capability
>     API is
>     > just so people can steal code?
>     >
>     > Again, I'm not saying they have to make that commitment, I'm just
>     > asking them to.
>
>     Part of working with a company that's trying to be open like we are is
>     understanding that not every utterance by every person here is the
>     formal written and undebatable policy of Linden Lab.  "LL" above
>     is some
>     combination of Tess and I, speaking off-the-cuff at Zero's office
>     hour.
>
>     One of the biggest challenges we face by investing in documentation is
>     that we're still experimenting and changing things.  It's not
>     clear what
>     exactly we should lock down.  Moreover, we're not feeling a lot of
>     competitive pressure on this front relative to other really urgent
>     things that we need to do.  So, we're not investing heavily in
>     protocol
>     documentation right now.  That almost certainly isn't a permanent
>     situation, but it's where we are today.
>
>     Most of the effort we do spend in formal protocol documentation is
>     going
>     to be under the auspices of the Architecture Working Group, since
>     anything we do there needs to be detailed and formal in order to gain
>     momentum and credibility.  That's not terribly helpful in the near
>     term,
>     but I hope that provides assurance that we don't intend to let the
>     status quo persist.
>
>     In other areas, we'll have to be a little more clever in making sure
>     things get documented correctly, and that's going to involve getting
>     help from you all.  We strongly encourage everyone who wants good
>     protocol documentation to pitch in here:
>     https://wiki.secondlife.com/wiki/Protocol
>
>     I'll encourage everyone at Linden Lab to participate in building this
>     out, but I'll have a much easier time of it if there's a lot of
>     outside
>     activity on those pages (thus being a very leveraged investment on our
>     part).
>
>     Rob
>
>
>     _______________________________________________
>     Click here to unsubscribe or manage your list subscription:
>     /index.html
>
>
>


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://lists.secondlife.com/pipermail/sldev/attachments/20071003/61ea9185/signature.pgp