[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

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

• From: Linda van den Brink <lvdbrink@b...>
• To: "'xml-dev@l...'" <xml-dev@l...>
• Date: Wed, 11 Oct 2000 16:55:01 +0200

It's good to know that one can send suggestions to the editor of a spec and
help create a better text that way. However, if w3c standards are in danger
of not being widely accepted/adopted because the specifications are not
readable, our suggestions may not be enough. If the w3c really wants to
improve the writing quality (read: understandability) of their specs, they
should decide what their main target audience is, figure out their writing
standards, and use technical writers, if not to actually write the
specifications, then at least to do a thorough review. 

And maybe it's a good idea to split specifications up in normative docs
(target audience: developers who implement the spec), written by the same
editors that write the specs today, with review input from tech writers, and
informative docs (target audience: users of the standard described in the
spec), written by tech authors with the normative document as input. These
informative docs could be sort of like the XML Schema part 0: primer. Better
if it would try more to rephrase the often difficult to read normative
statements in parts 1 and 2. Another idea could be to have the informative
docs in the form of explanatory comments on the actual spec document, like
Tim Bray's Annotated XML. 

It's very often a problem to find resources (i.e. money) for this kind of
thing. It's a matter of deciding that good documentation is a prerequisite
for success. Which in this case it could well be. 

Linda

Len Bullard wrote: 
> Yes.  The most helpful thing when writing 
> is having other intelligent eyes read it. 
> Those who prepare edits according to 
> some procedure, eg
> 
> o Text of Spec:  Exact quote with address (version, para number, page
> number)
> 
> o Problem with Text:  precision precision precision (if you 
> don't like 
> the concept, that isn't an editorial issue)
> 
> o Suggested Fix:  Precise text replacement.
> 
> Send these to the editor and you can almost always 
> guarantee a good response.  Do it more than once 
> and you may be drafted into the committee.  Don't 
> expect an immediate reply.  Sometimes you are sending 
> to someone under a deluge of work and if they 
> manage to send a "thanks" that means they read it. 
> Also, they will receive the same comments for the 
> same sections.  They may disagree and they are the 
> editor. 
> 
> The standards world is always looking for a few good eyes.

• Follow-Ups:
  • Re: Improved writing -- who's going to pay for it?
    • From: Ronald Bourret <rpbourret@r...>

• Prev by Date: Re: RELAX to ISO
• Next by Date: XML Developers Day Call for Presentations --- FIRST AND LAST CALL
• Previous by thread: RE: Improved writing -- who's going to pay for it?
• Next by thread: Re: Improved writing -- who's going to pay for it?
• Index(es):
  • Date
  • Thread