Re: Square-bracket output of Definition in specs is bogus

* Roy T. Fielding wrote:
>Any style commonly used in technical writing would be better. I gave
>you an example from the IEEE standards.  And, no, it is neither 
>understood nor appreciated by the target audience -- why don't you
>ask them?

I am afraid I would not find anyone who would claim that the XML 1.0
Recommendation does not define what a "well-formed XML document" is,
which is however a consequence of not understanding that [Definition:]
is a normative part of the document. So it seems you are overstating
the problem. I agree that this style is not perfect, but it does not
actually hinder anyone accessing the technical content.

>I did and only one of the ten people I asked said it was better than
>no highlighting at all.  The only reason they go along with it is 
>because they want to be consistent with W3C spec production.

How many of these people were people who just do some programming in
their spare time or hobbyists who do some web page authoring in their
spare time? It would seem you've only asked people editing W3C specs,
that's not a very representative group for the target audience for
most W3C Technical Reports and proper markup and style is much more
important to people who are not experienced readers of technical
writings.

Maybe you could modify a sample specification (e.g. by modifying the
XMLSpec transformation to generate the desired markup) with the best
alternate markup and style you can come up with? I think this would
greatly ease reviewing your change proposal. It would be a pity if
separate groups come up with different replacement style, we should
rather try to come up with the best alternative which would then be
universally adopted.
-- 
Björn Höhrmann · mailto:bjoern@hoehrmann.de · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

Received on Wednesday, 8 December 2004 23:36:12 UTC