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

["Abel, Scott" <sabel@cincom.com>]

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

I applaud Linda van den Brink's suggestion to utilize tech writers to assist in crafting easily understandable specifications/standards. Far too often, technical communicators are not considered necessary to the success of a project. They are usually brought in AFTER a project or product starts to fail ... or when complaints warrant some type of management action. Unfortunately, at that point, it's usually too late. Writing good documentation for a bad product doesn't make the product better.

Hopefully, the industry will begin to bring technical writers in at the beginning of product development, not after the fact. Doing so will help eliminate many of the problems Linda mentioned.

Scott Abel

-----Original Message-----
From: Linda van den Brink [mailto:lvdbrink@baan.nl]
Sent: Wednesday, October 11, 2000 9:55 AM
To: 'xml-dev@lists.xml.org'
Subject: RE: Improved writing -- who's going to pay for it?

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.