[Standards] long specs

Peter Saint-Andre stpeter at stpeter.im
Mon Feb 27 23:02:02 UTC 2012


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

On 2/15/12 1:07 PM, Peter Saint-Andre wrote:
> On 2/15/12 12:48 PM, Kurt Zeilenga wrote:
> 
>> On Feb 15, 2012, at 8:26 AM, Peter Saint-Andre wrote:
> 
>>> I'd be willing to work on this, but I want to make sure that 
>>> people think there's value in doing so.
> 
>> Personally, I not sure what I hate more, overly long documents
>> or specifications unnecessarily split over multiple documents.
> 
>> I don't consider XEP 45 or XEP 60 to be overly long.
> 
> Half the feedback I receive is (a) it's too hard to read a long
> spec. The other half is (b) it's too hard to read multiple specs.
> For XEP-0060, the feedback is heavily weighted toward (a). For
> XEP-0045, it's about evenly weighted. My conclusion is that we
> really need to split up XEP-0060, and that splitting XEP-0045 into
> user vs. admin use cases would be helpful.

Over the weekend I took a rough cut at splitting up XEP-0045. Here's
what I came up with (page lengths are based on print-to-PDF in Firefox):

XEP-0045 = 141 pages

Architecture, Requirements, Discovery, Security = 35 pages

Occupant Use Cases = 56 pages

Administration = 68 pages

The document that most client developers would read is the one on
occupant use cases. Would they find 56 pages less intimidating than
141 pages? Probably. (And probably we could move some stuff out of the
occupant use cases -- requesting voice, that kind of thing.) Would it
be worth our time to split things up this way? Perhaps.

Peter

- -- 
Peter Saint-Andre
https://stpeter.im/


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

iEYEARECAAYFAk9MC2kACgkQNL8k5A2w/vxtXgCdEcshiapn1LRQT79pwrQ0k6QO
4+AAoM3YYDxYJvoHAzsKtuF47LYLKOow
=slhU
-----END PGP SIGNATURE-----



More information about the Standards mailing list