[standards-jig] On documenting the use of other technologies

Iain Shigeoka iain.shigeoka at messaginglogic.com
Tue Sep 3 11:01:55 CDT 2002


On 9/2/02 8:29 PM, "Robert Norris" <rob at cataclysm.cx> wrote:

> Now, while I agree that SASL is not widely understood, is it really our
> place to inform developers on how a particular technology works? The
> SASL JEP cleary states in the introduction that a reader should have a
> clear understanding of the SASL RFC (2222) before reading. The reason
> for this is simple - JEP 34 is not a standalone document, but is a part
> of the larger framework defined in RFC 2222.

Referencing relevant docs should be enough in standards JEPs.  Conciseness
is important and the only way to adequately explain SASL within your JEP
would be to recreate RFC 2222 and several other RFCs.  In general, I believe
that you should put as little as necessary in a JEP to describe it,
referencing other specifications as necessary.  Otherwise it will be hard to
decide when to stop.  Taken to the extreme you'd have to describe how TCP/IP
works?  :)

If there is enough demand or you have a desire to do so, you could write an
implementer's guide, or an informational JEP regarding implementation
issues.  Even this seems like above and beyond the call of duty (although
nice to have) documentation since there should be at least 2
implementations, at least one of which is open source.

-iain




More information about the Standards-JIG mailing list