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

["Simon St.Laurent" <simonstl@simonstl.com>]

At 07:53 PM 10/15/00 -0500, Robin Cover wrote:
>It's analogous in my view to software development.  The agency
>producing the spec should assume responsibility for producing
>clear exposition of the formal language.  Another principle
>comes into play, however: that software architects and
>programmers should not be allowed (much less required) to
>produce the general-user-level documentation.  They are too
>close to the problem, and too pickled in the jargon that
>assumes familiarity with spec-talk discussion.  They cannot
>easily disabuse themselves of the kind of knowledge that may
>be essential for the newcomer/outsider.

There are rare exceptions, but it's unusual for experts and newcomers to be
able to communicate off the bat.  Without the shared experiences that give
the experts their expertise, there's always a vocabulary and paradigm
mismatch.

>This principle, if
>applicable, suggests that W3C would commission and review
>user-level documentation written by an "outsider".  Such an
>arrangement seems preferable to what we have now: dozens of
>publishers wanting to rake in easy money by employing non-
>expert writers to produce (quickly!) largely unrefereed works,
>which -- in my experience -- typically contain errors of fact
>as well as bad opinionated advice that would not pass muster if
>it were reviewed by the technical committee producing the spec.

Computer books (and publishing generally) is a tough racket, all right.  I
started out as one of those non-expert writers, though I fortunately had an
experienced referee looking over my shoulder.  Even so, the process of
creating good books this way is iterative and public, and involves learning
from mistakes - virtually no non-expert can get it all right the first
time.  Large-scale peer review can help, but all too often happens _after_
publication.

At the same time, having experts write those books often doesn't work well
either, for the reasons noted above.  Non-experts teaching a subject can
sometimes take their experience of learning the material and apply it to
the book - something that can produce better tutorials, I think.

Generally speaking, I'd like to see the W3C consider the approach you've
described above, since it seems to combine the best possibilities of both
ends of the process in a way that generally isn't possible for commercial
publishers. Publishers do sometimes have expert oversight on series, which
significantly improves the content, but this is rather difficult for most
of them.

Simon St.Laurent
XML Elements of Style / XML: A Primer, 2nd Ed.
XHTML: Migrating Toward XML
http://www.simonstl.com - XML essays and books