"Clean Specs"

[Frank Boumphrey]

Murray wrote

<<In my experience as a technical writer, I have discovered that
the act of explaining the application of a technical design
can, in many cases, lay bare its flaws. >>

I agree with this. The writer of the spec. presumably knows what they want
to say, but often don't say it, and it's only in the process of explaining
the spec that the flaw is laid bare. For example when I tried to explain
this I realised that it was in fact meaningless.

<<Non-standard extensions, when used, may change the behavior of functions
or facilities defined by this
recommendation. In such cases, the implementation documentation must
define an environment in which a document can be parsed and rendered
with the behavior specified by this recommendation.>>

Cooperation between
>writers and designers often results in designs that take the
>end-user into account.

And that surely is the whole idea!

Frank

Frank Boumphrey

XML and style sheet info at Http://www.hypermedic.com/style/index.htm
Author: - Professional Style Sheets for HTML and XML http://www.wrox.com
CoAuthor:  XML applications from Wrox Press, www.wrox.com
Author: Using XML on the Web (March)
----- Original Message -----
From: Murray Maloney <murray at muzmo.com>
To: XML-Dev Mailing list <xml-dev at ic.ac.uk>
Sent: Sunday, February 07, 1999 6:34 PM
Subject: Re: "Clean Specs"


>James' has reiterated a suggestion that has been put forward
>by others in the past -- notably Dan Connolly and Tim Berners-Lee.
>Sadly, professional writers are not always easy to come by, and
>when they are they usually expect compensation -- gotta make a
>living, dontcha know. A professional technical writer was hired
>by W3C for the HTML 4.0 specification.
>
>The XML WG did have at least one professional writer and one
>professional editor on board, and many of those who were not
>professional writers/editors could not fairly be categorized
>as amateurs given their academic and professional histories.
>
>In my experience as a technical writer, I have discovered that
>the act of explaining the application of a technical design
>can, in many cases, lay bare its flaws. Cooperation between
>writers and designers often results in designs that take the
>end-user into account.
>
>Regards,
>
>Murray
>
>
>
>
>xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
>Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on
CD-ROM/ISBN 981-02-3594-1
>To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
>(un)subscribe xml-dev
>To subscribe to the digests, mailto:majordomo at ic.ac.uk the following
message;
>subscribe xml-dev-digest
>List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)
>
>


xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)