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

[Linda van den Brink <lvdbrink@baan.nl>]

> 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 
Yes. Two different audiences. If I could solve this one regardless of time
and budget, I'd decide to 
- Write the specification (normative doc) for implementors
- Write an informative document for users
Where the second document is based on the first and starts being written
some time during the draft stage of the first. 

Still, both types of documents need involvment of tech writers. 

> 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.
> 
> 
>