[Standards-JIG] Re: CALL FOR FEEDBACK: JEP-0060

Peter Saint-Andre stpeter at jabber.org
Wed May 24 17:07:27 UTC 2006


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Heiner Wolf wrote:

> I know I am about to get in hot water, but I think the JEP is too fat.
> It printed 100 pages with small fonts.

Emperor Joseph II: But there are simply too many notes, that's all. Just
cut a few and it will be perfect.

Mozart: Which few did you have in mind, Majesty?

:-)

On my printer, version 1.8 of JEP-0060 is 130 pages. A page count
reveals the following (totals may not round to 130):

Front matter, end matter -- 10 pages

Intro, requirements, terminology -- 8 pages

Entity use cases (disco etc.) -- 7 pages

Subscriber use cases -- 24 pages

Publisher use cases -- 11 pages

Owner use cases -- 30 pages

Collections -- 9 pages

Feature summary, error codes, implementation notes -- 13 pages

Jabber Registrar considerations -- 9 pages

XML schemas -- 9 pages

Version 1.7 was 69 pages. So what happened?

First, I added very detailed error flows. No other JEP specifies the
error flows in this much detail (the RFCs don't, either). And every
error flow has at least one example. That's a lot of text and examples,
especially given that some of use cases have 10 error flows. But IMHO
it's the job of a spec to specify things in detail, since that makes it
easier for implementors. I think this accounts for the great bulk of the
added pages.

Second, I specified the service discovery flows in more detail (the
entity use cases). They were underspecified before and implementors got
confused.

Third, I added the feature summary and the explanation of error codes
(again, more content to help implementors).

Once you also add in the introductory example, a few more implementation
notes, better schemas, and a longer revision history, you pretty quickly
go from 69 pages to 130 pages.

> I understand, that most of the complexity will be implemented by
> servers, but I doubt, that the client part is simple (remember: jabber
> clients should be simple?).

I am not convinced that you have a problem with the complexity of the
protocol (have you implemented it?) but with the length of the document.
Again, comparing version 1.7 to version 1.8 reveals that we've mostly
added explanatory text and a whole lot of examples, not new protocols.
In fact, the intent with version 1.8 was to make the spec easier to
read, not (if at all possible) to add or change protocols. So your
criticism of complexity would have applied just as well to version 1.7
(69 pages) as to version 1.8 (130 pages).

> I am also a fan of simple specs for the server part. Servers usually
> tend to have lots of code, but this is because they have to cope with
> the real world and evil clients. Not, because they implement complex
> services.
> 
> This is not the time to go into details. I am saying that a pubsub
> specification on top of an XML based protocol could be simpler, smaller,
> easier. It should be.

Yes, this *is* the time to go into details. Speak now or forever hold
your peace. I sure don't want to have this discussion again after
version 1.8 is published, because my hope is that this is pretty much
the end of the line for changes to the spec (other than minor fixes and
corrections).

> I know JEP-0060 went a long way and there are already big investments in
> documentation, code and know how. Despite all this, I propose to make a
> new document and extract only the essentials.

Which use cases do you think are essential?

Would it help to more clearly mark (at the beginning of each section)
which use cases are optional, which are recommended, and which are
required? That information is also provided in the feature summary, but
perhaps people don't see that until later in the document so they get
scared off.

> It might be possible to separate the document into a pubsub core and
> extensions. The core should have a simple pub/sub mechanism. Collection
> Nodes, should be a separate JEP. 

Perhaps yes. But again they are marked as OPTIONAL.

> I am sorry for the blog/news-oriented
> people, but I'd scrap items for pubsub-core and store data in nodes
> only. Items could be an extension with the node returning the
> first/default item. 

So what would be published? Currently, to publish means to publish an
item. I have a hard time seeing what publication means if you don't
publish an item, but perhaps I'm missing something.

> Maybe implementation notes could be split off. They
> are important, but they make the spec heavy 

Perhaps it would help to have a tutorial of the kind that Matt suggests?

> and people judge specs by
> the page count. 

And here I thought people judged specs by how clearly they are written,
how many helpful examples they have, etc. My philosophy is to include a
whole lot of examples, and in general implementors tell me they like
that. Version 1.7 had 106 examples, version 1.8 has 209. That probably
accounts for 50% or more of the added pages. Which examples would you
like me to remove?

> Remember SIP and SIMPLE? 

RFC 3261 is 268 pages and it has very few examples (the examples don't
even start until page 212 and go until page 218!). The analogy is not
very helpful or appropriate, I think. The important question is: how
complex is the protocol? Not: how long is the document? The fact that
RFC 3261 is 268 pages long but has only 6 pages of examples tells you
something! By contrast, JEP-0060 has so many examples that it puts RFC
3261 to shame.

"We put the example in example.com." :-)

> And yes, I know that 1/2 of the
> spec is XML, examples and schema. I think it is still too much for a
> pubsub-core document.

So which XML, examples, and schemas would you pull out? Which error
flows? Which uses cases?

> I don't think, that it is a good way to finish now "what we already
> have" and then add simplifications as separate JEPs. It would be better
> to restart simple and then draw the code for extensions from JEP-0060.

Would you prefer one JEP for required features (MUST implement), one JEP
for recommended features (SHOULD implement), and one JEP for optional
features (MAY implement)? Would implementors really find that less
confusing? I have my doubts. Perhaps pushing some of the optional
features to appendixes would help, and also clearly specifying which use
cases are required, recommended, and optional (see above). But I don't
see how splitting the spec into three documents is going to really help
implementors. (Would that help with JEP-0045, too? Should we do that for
all specs, or only the specs that are longer than 50 pages? Etc.)

With version 1.8 I tried as hard as I could to make the spec clearer,
easier to read, full of examples, and developer-friendly. If I have not
succeeded in that goal, then I am open to making further improvements.
But I don't think that making wholesale changes to address the fear of
large page counts is a good use of my time, especially since the large
page count resulted from my efforts to make the spec much easier to
understand and implement (based, I should add, on direct feedback from
developers who have implemented the spec).

Peter

- --
Peter Saint-Andre
Jabber Software Foundation
http://www.jabber.org/people/stpeter.shtml

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEdJLPNF1RSzyt3NURAmiHAJ4mdeh6T9DCOH/pq9aRu2FBYokV9wCfQlj5
SAR+FxXTIZcW3qgR6EkVQtE=
=R/Dq
-----END PGP SIGNATURE-----
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 3641 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://mail.jabber.org/pipermail/standards/attachments/20060524/8819ce2b/attachment.bin>


More information about the Standards mailing list