"Clean Specs"

[Buss, Jason A]

>Perhaps in this modern world, some of the rather large fees charged 
>by W3C for membership could go towards hiring some technical writers 
>to address this issue.  IMNSHO, the amount of time that we've all 
>spent thrashing about with namespaces is an example of intelligence, 
>time and energy that could have been avoided by a standard that 
>addressed some of the issues better.

>If standards are the way we'll do business (and I'm all for that!) 
>then why not invest in the best possible standards up front?  Just 
>because IETF and other traditions made do without, doesn't mean that 
>we should be penny wise and pound foolish now.  Clarity is a net gain 
>for W3C members, and for the larger community, as the cost of 
>incompatible implementations is significant.

Avi

At 5:40 PM -0600 2/7/99, W. Eliot Kimber wrote:
> The XML WG was an all-volunteer project, as are most standards efforts.
> Those of us who participated did so primarily as a personal commitment,
not
> as something our employers (those of us who have them) pay us to do.
>
> Standards development is not a commercial process--there is no budget from
> which technical writers might be hired.  The W3C only administers, it does
> not fund. Same for ISO. Some national bodies do fund some standards
> development (BSI, the British Standards Institute), but that funding will
> tend to be used to support the technologists developing the standard and
> not writers crafting the words.
>
> So while it's true that most, if not all, specifications could benefit
from
	> professional writers, it usually isn't an option for standards
developers 

> > Well, has anyone considered employing real, professional technical
> > authors to write the specifications?
> 
	>As chair of the DOM WG, I (and I think the editors of the specs) 
	>would be overjoyed were someone to volunteer the services of a 
	>real, professional technical author who could help in the process
of 
	>getting good specs out the door. However, as has been pointed out 
	>by others on this list, this support is difficult to find, as W3C 
	>seldom has these resources available. 

	Maybe it is time some of us who have been "put off" by the way the
Namespaces recommendation to offer our services, under the auspices of the
WG for XML and XML related standards, to go through and annotate the drafts
and recommendations, as they come up for the vote.  

	I didn't have trouble with the XML recommendation or the XSL working
draft.  The DOM took me a couple of reads, and I have read the namespaces
recommendation 3 times and still have some questions, but I am looking here
and other places to find the answers before I climb up in here and get all
surly with the spec writers.

	I know there are a number of people who have read the spec and are
upset with the concept of namespaces.  I am still trying to grasp parts of
it myself.  But I think a lot of this is because I am a technical writer by
trade.  I prepare documents for the end-user.  I am conditioned to write
things from the perspective of the person actually utilizing the documents;
I still wince at typos.  If I hadn't had the background in SGML that I have,
I would have been lucky to get past the XML spec itself.

	IMHO, if the working groups would like to see the services of
technical writers utilized, they should probably just come forward and ask.
I imagine through the W3C site or something.  I think I have seen postings
from Paul saying he had been working on annotated versions of the
recommendations.  If tech writers would like to see this, and it appears
that the WG's would appreciate the help, I don't see why efforts could be
made towards this.  I know I would probably take up the opportunity to do
such work, even if it is on a voluntary basis.  Even if some don't have the
time, surely someone would even a small amount of time to analyze and make
some notes, so if someone becomes available, they could come in with
something to start from.  Even if it took a series of writers throughout the
development process, the outcome would likely justify the effort.

	Any suggestions? comments?

Jason A. Buss
Single Engine Technical Publications
Cessna Aircraft Co.
jabuss at cessna.textron.com
"I don't have your solution, but I do admire your problem..."
	    



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)