xml-dev - Re: Improved writing -- who's going to pay for it?

[Eric Bohlman <ebohlman@earthlink.net>]

10/11/00 5:02:09 PM, Ronald Bourret <rpbourret@rpbourret.com> wrote:

>Rick JELLIFFE wrote:
>> 
>> The prime readers of XML Schemas specification is implementers of XML
>> Schema processors; a secondary audience is developers of XML Schemas
>> (hence the Primer).
>
>I both agree and disagree with this statement. On the agreement side,
>implementers are the ones who actually enforce the spec, so it is
>vitally important that they understand it. (They also win by virtue of
>being in the minority -- if more people wrote implementations than
>schemas, the spec would probably target the authors, not the
>implementers.)
>
>On the disagreement side, I'm not sure I like the implication that
>schema authors aren't important. While I don't mean to say that you
>meant this (I can't imagine that you did), I have an uneasy feeling that
>this sort of attitude is exists in the spec writing community -- sort of
>a macho "if you can't understand it you don't deserve to" thing. And
>while I do agree that specs will never be accessible to all readers, I
>think the line should be drawn further out than it currently seems to
>be.


I don't really see that implication here.  The problem is that implementers 
need a much greater level of nitpicky details than authors do, largely due to 
the "be liberal in what you accept and conservative in what you send" 
principle.  They need to know exactly how lots of corner cases should be 
handled, cases that very few authors would actually generate, and that sort of 
thing requires mind-numbing detail.  A spec that avoids the levels of detail 
that are irrelevant to anyone but implementers, and therefore would be useful 
to authors, is going to be useless to implementers.  The real issue, as I see 
it, is that writing *schemas* and writing *schema processors* are two 
completely different activities that essentially require different *kinds* of 
knowledge and it is difficult for a single document to convey both 
simultaneously (for example, the optimal organization of the material is 
different for those who are going to be designing schema processors and those 
who are designing schemas).  It's really the difference between interface and 
implementation.

It is often the case that internal complexity is needed to achieve external 
simplicity (the classic illustration is an automatic transmission, where the 
design engineers have to deal with lots of detail precisely so the drivers 
don't).  I think this is one of those cases.  In this case, if we need a 
single spec (we probably do), I'd rather see it be implementer-friendly than 
author-friendly for the simple reason that a good tech writer could 
"translate" the former to the latter but not vice-versa; you can filter out 
excessive detail in preparing a derivative work, but you can't conjure up 
missing detail.  Schema developers shouldn't need to be working off the same 
spec document as schema processor developers, just as programmers shouldn't 
need to be working off the CAD files used to design the CPU at the gate level.