"Clean Specs"

[James Robertson]

At 06:43 8/02/1999 , Tim Bray wrote:

  | Actually, here's another piece of evidence that supports your position.
  | Recently, in an effort to refresh my memory as to why something in XML 1.0
  | was the way it was, I went back and reviewed a whole bunch of the 
  | XML SIG mailing list correspondence from back in '97 while the important
  | issues were being thrashed out.  Things such as white-space handling
  | and public identifiers and so on were being debated passionately by
  | people who were obviously deeply erudite as to the pros and cons of the
  | issues; in the thousands and thousands of emails, though, there is
  | almost no input as to the structure and presentation of the XML spec -
  | everyone was too focused on the content.  I think there's *definitely*
  | a lesson there. -Tim

I think I'll make my point more strongly here, as I think Tim highlights
this issue in his post.

As a whole, we can be considered the "professionals" or "specialists"
in the areas of XML, etc.

However, there is a whole, much larger, group of professional people
who are the experts in: writing stuff that makes sense. 

They are called technical authors.

The XML WG wouldn't think of seriously discussing say, OS filesystem 
design. I would ask why they think they have the
skills and qualifications to write a large and complex technical
document, so that it makes sense?

The specification document is read by the whole world, and is essentially
the only medium that the WG uses to communicate its ideas
widely. So it's a document worth doing properly, not something that
should be written by technical specialists and amateur authors.

Now, this point of view is very new to me as well, and it's come
about due to having worked for the last year with a group of 
technical authors. And they really do know their stuff ...

So from now on, I'm going to stick to designing and coding, and
consult the experts when I need to write serious documentation.

Just some thoughts for the day,

J


-------------------------
James Robertson
Step Two Designs Pty Ltd
SGML, XML & HTML Consultancy
http://www.steptwo.com.au/
jamesr at steptwo.com.au

"Beyond the Idea"
 ACN 081 019 623

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)